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Preface 


Welcome  to  the  Programmer's 
Introduction 


The  Apple  IIGS®  is  a  new  kind  of  computer.  It  offers  precise  color 
graphics,  sophisticated  sound  hardware,  i  large  memory  capacity, 
and  an  exiensive  toolbox  of  programming  routines — giving  you 
programming  resources  without  precedent  among  personal 
computers.  The  Programmer's  Introduction  to  the  Afple  liGS  gets 
you  started  writing  programs  that  take  advantage  of  these  unique 
features. 

You  needn't  be  an  expert  programmer  to  benefit  from  this  book, 
but  we  do  assume  that  you  know  some  fundamentals.  Your 
background  will  most  likely  determine  your  approach. 

□  If  you  are  familiar  with  programming  other  Apple®  11 
computers,  and  wondering  how  difTerent  Apple  IIGS 
programming  might  be... 

□  If  you  are  familiar  with  programming  the  Macintosh® 
computer,  and  wondering  how  similar  Apple  IIGS  programming 
might  be... 

□  If  you  are  familiar  with  programming  other  computers,  and 
wondering  how  rewarding  Apple  IICS  programming  might  be... 

□  If  you  are  familiar  with  using  the  Apple  IIGS,  and  wondering 
how  much  fun  Apple  IIGS  programming  might  be... 

...this  book  will  help  get  you  started.  It  can't  be  a  complete 
programming  course,  but  it  does  cover  the  major  features  that  set 
the  Apple  IIGS  apart  and  make  it  an  exciting  machine  to  write 
programs  for. 


xill 


You  should  be  familiar  with  ihc  Apple  IIGS,  at  least  from  a  user's 
perspective,  before  you  start  this  book,  In  particular,  you  should 
understand  how  to  start  the  system  and  how  to  use  the  keyboard, 
mouse,  and  disk  drives. 

We  don't  teach  you  any  programming  languages  here.  The  books 
listed  in  the  next  seaion  under  "Roadmap  to  the  Apple  IIGS 
Technical  Manuals"  can  help  you  with  C  and  65816  assembly 
language.  The  other  Apple  IIGS  technical  manuals  cover 
individual  topics  in  far  greater  detail  than  we  can  here;  please 
consult  them  as  needed. 

<*  Toolbox  manual:  It  is  not  possible  to  write  the  kind  of  program 
described  here  wiihout  the  aid  of  the  Apple  flGS  Toolbox 
Reference.  We  give  lots  of  examples  and  general  call 
descriptions  in  this  book,  but  you'll  need  both  volumes  of  the 
Toolbox  Reference  if  you  want  to  write  your  own  applications. 


Roadmap  to  me  Apple  IlGS  technical 
manuals 

The  Apple  IIGS  per.sonal  computer  has  many  advanced  features, 
making  it  more  complex  than  earlier  models  of  the  Apple  IL  To 
describe  it  fully,  Apple  has  produced  a  suite  of  technical  manuals. 
Depending  on  the  way  you  intend  to  use  the  Apple  IIGS,  you  may 
need  to  refer  to  a  select  few  of  the  manuals,  or  you  may  need  to 
refer  lo  most  of  them. 

The  technical  manuals  are  listed  in  Table  P-1.  Figure  P-1  is  a 
diagram  showing  the  relationships  among  the  difTerent  manuals. 
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Introductory  manuals 


The  introductory  manuals  are  for  developers,  computer 
cnlhusiasLs.  and  other  Apple  IIGS  owners  who  need  technical 
information.  As  introductory  manuals,  their  purpose  is  to  help  Uie 
technical  reader  understand  the  features  of  the  Apple  UGS, 
particularly  the  features  that  are  different  from  other  Apple 
computers, 

■  The  teclinical  iiitroductloii:  The  Technical  Introduction  to  the 
Apple  lies  is  the  first  book  in  the  suite  of  technical  manuals 
about  the  Apple  IIGS.  It  describes  all  aspects  of  the  Apple  IlGS, 
including  its  features  and  general  design,  the  program 
environments,  the  toolbox,  and  the  development  environment. 

■  The  programmer's  Introduction  (this  book)t  Wtien  you  start 
writing  Apple  liGS  programs,  the  Programmer's  Introduction  to 
the  Apple  IIGS  provides  the  concepts  and  guidelines  you  need. 
It  is  not  a  complete  course  in  programming,  only  a  starting 
point  for  programmers  writing  applications  that  use  the  Apple 
desktop  interface  (with  windows,  menus,  and  the  mouse).  It 
introduces  the  routines  in  the  Apple  liGS  Toolbox  and  includes 
a  sample  event-driven  program. 


Mactiine  reference  manuals 

There  are  two  reference  manuals  for  the  machine  itself.  They 
contain  detailed  specifications  for  people  who  want  to  know 
exactly  what's  inside  the  machine- 

■  The  hardware  reference  naanuaL  The  Apple  IIGS  Hardwars 
Reference  is  required  reading  for  hardvi^are  developers  and 
anyone  else  who  wants  to  know  how  the  machine  works. 
Information  for  developers  includes  the  mechanical  and 
electrical  specifications  of  all  connectors,  both  internal  and 
external.  Information  of  general  interest  includes  descriptions 
of  the  internal  hardware  and  how  it  affects  the  machine's 
features. 
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■  The  firmware  refcreJice  manxiat  The  j^ppfe //(j^Hrwiti-'flfig 
Reference  describes  programs  and  subroutines  stored  in  the 
machine's  read-only  memory  (ROM).  The  Firmware  Reference 
includes  information  about  interrupt  routines  and  low-level  I/O 
subroutines  for  the  serial  ports,  the  disk  port,  and  for  the 
Desktop  Bus  interface,  which  controls  the  keyboard  and  the 
mouse.  The  Firmware  Reference  also  describes  the  Monitor 
program,  a  low-level  programming  and  debugging  aid  for 
assembly-language  programs. 


Th0  toolt>ox  monuals 

Like  the  Macintosh,  the  Apple  TIGS  has  a  built-in  toolbox  of 
software  routines.  The  two  volumes  of  the  Apple  lies  Toolbox 
Reference  completely  describe  the  calls  and  data  structures  for  all 
tool  sets,  and  also  tell  how  to  write  and  install  your  own  tool  set. 

The  desktop  Interface  is  If  you  are  developing  an  application  that  uses  the  desktop 

described  in  Chopfer  1.  interface,  or  if  you  want  to  use  the  Super  Hi-Res  graphics  display, 

you'll  find  the  toolbox  indispensable. 


The  Progrcimmer's  Workshop  manual 

The  Apple  IIGS  Programmer's  Workshop  (APW)  is  the 
development  environment  for  the  Apple  IIGS  computer — 2.  set  of 
programs  that  enables  developers  to  create  application  programs. 
The  Apple  IIGS  Programmer's  Workshop  Reference  describes  the 
APW  Shell,  Editor,  Linker,  and  utility  programs;  these  are  the  parts 
of  the  workshop  that  all  developers  need,  regardless  of  which 
programming  language  Ihey  use. 

The  APW  reference  manual  includes  a  sample  program  to  show 
how  to  create  an  application.  It  also  describes  object  module 
format,  the  file  format  used  by  all  APW  compilers  to  produce  files 
loadable  by  the  Apple  IIGS  System  Loader, 


Programming-ronguage  monuals 

Apple  currendy  provides  a  65C816  assembler  and  a  C  compiler. 
Other  compilers  can  be  used  with  the  workshop,  provided  that 
they  follow  the  standards  defined  in  the  Apple  IIGS  Programmer's 
Workshop  Reference. 


xvlll 


Preface:  Introduction  to  the  Programmer's  tniroducffon 


There  is  a  separate  reference  manual  for  each  programming 
language.  Each  manual  irrdudes  the  specifications  ot  ihe  language 
and  of  the  Apple  IIGS  libraries  for  the  language,  and  describes 
how  to  use  the  a!>semblcr  or  compiler  for  that  language.  The 
manuals  for  the  languages  Apple  provides  arc  the  Apple  HCS 
Programmer's  Workshop  Assembler  Reference  and  the  Apple  IIGS 
Programmer's  Workshop  C  Reference. 

*  Note:  The  Apple  IIGS  Programmer's  Workshop  Reference  and 
tiie  two  programming-language  manuals  are  available  through 
the  Apple  Programmer's  and  Developer's  Association  (APDA). 


Operating-system  monuals 

There  are  two  operating  systems  that  run  on  the  Apple  IIGS; 
ProDOS®  16  and  ProDOS  a.  Each  operating  system  is  described 
in  its  own  manual:  the  Apple  IIGS  ProDOS  16  Reference  and  the 
ProDOS  8  Technical  Reference  Manual.  ProCKDS  16  uses  the  Full 
power  of  the  Apple  IIGS.  The  ProDOS  l6  manual  describes  its 
features  and  includes  information  about  the  System  Loader,  which 
works  closely  with  ProIX)S  l6  to  load  program  segments  into 
memory. 

ProDOS  8,  previously  called  ProDOS,  is  the  standard  operating 
system  for  most  Apple  II  computers  with  8-bit  CPUs.  It  also  runs 
on  the  Apple  IIGS,  but  it  cannot  access  certain  advanced  Apple 
IIGS  features. 


All-Apple  manuals 

There  are  two  manuals  that  apply  to  all  Apple  computers:  Human 
Interface  Guidelines:  The  Apple  Desktop  Iruerface  and  Apple 
Numerics  Manual  If  you  develop  programs  for  any  Apple 
computer,  you  should  know  about  those  manuals. 
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The  Human  Interface  Guidelines  manual  describes  Apple's 
siandards  for  the  desktop  interface  of  any  program  that  runs  on 
Apple  camputers.  If  you  are  writing  a  commercial  application  for 
the  Apple  HGS,  you  should  be  familiar  with  the  contents  of  this 
manual. 

The  Apple  Numertcs  Mantial  is  the  reference  for  the  Standard 
Apple  Numeric  Environment  (SANE™),  a  full  implementation  of 
the  IEEE  Standard  for  Binary  Ftoating-Point  Arithmetic  (IEEE  Std 
754-1985).  If  your  application  requires  accurate  or  robust 
arithmetic,  you'll  probably  want  to  use  tiie  SANE  routines  in  the 
Apple  IIGS. 


How  to  use  this  book 

The  Programmer's  tnlroducHon  is  not  a  tutorial.  Rather  than  ask 
you  to  type  in  line  after  line  of  code,  we've  built  the  book  around 
a  finished  example — a  sample  program  named  HodgePodge. 
HodgePodge  is  a  fully  functioning  framework  of  an  application 
that  demonstrates  most  of  the  programming  concepts  we  present 
in  this  book.  More  than  thai,  HodgePodge  is  a  rather 
heterogeneous  collection  of  generally  u.seful  Apple  IIGS 
routines — hence  its  name.  You  are  invited  to  study,  copy,  or 
incorporate  any  of  those  routines,  wholesale  or  piecemeal, 
unchanged  or  greatly  altered,  into  your  own  programs. 

Stan  by  reading  Chapter  1.  1:  introduces  the  basic  concepts  of  this 
book — event-driven  programming,  the  desktop  user  interface,  the 
Apple  IIGS  Toolbox,  and  program  segmentation. 

Then  run  HodgePodge  to  see  what  ii  does.  At  that  point  you 
should  be  ready  for  Chapter  2.  an  extensively  annotated  set  of 
source  listings  of  the  principal  parts  of  HodgePodge.  The  listings 
give  you  the  big  picture  on  how  event-driven  programs  are 
organized,  demonstrate  how  heavily  desktop  programming  relies 
on  toolbox  calls,  and  function  as  templates  for  you  to  use  in  your 
own  programming.  Complete  source  listings  in  Pascal,  C,  and 
65816  assembly  language,  are  in  Appendixes  E  through  G. 
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Chapters  3  through  8  expand  further  on  ihe  concepts  of  toolbox 
use,  memory  management,  program  scgmeniation,  the 
development  environment,  and  specialized  program 
requirements.  These  chapters  include  sample  source  listings  where 
appropriate,  but  they  also  discuss  important  Apple  I  ICS  concepts 
not  represented  in  any  of  the  samples.  They  are  overviews 
designed  to  give  you  ideas  to  pursue  in  your  own  programming 
when  aided  by  other  reference  manuals. 

Chapter  9  is  a  brief  wrap-up  that  summarizes  general  program 
design  ideas  and  shows  where  lo  go  for  further  help. 

Appendixes  include  hints  on  converting  existing  Macintosh 
applications  to  run  on  the  Apple  IIGS,  and  enhancing  existing 
Apple  I!  applications  lo  lake  full  advantage  of  the  new  Apple  IIGS 
features, 

">  Note:  Please  don't  feel  that  you  need  to  read  this  book  in  any 
order.  Skipping  around  among  programming  examples, 
explanations,  and  theory  may  be  the  best  way  to  absorb  the 
material  presented  here.  Most  important  of  all,  experiment  on 
the  Apple  IIGS  as  you  go  along.  Use  HodgcPodge  or  write  your 
own  examples. 


Terms  and  conventions 

This  book  may  define  certain  terms  in  a  slightly  different  manner 
from  which  you  are  accustomed.  Here  are  two: 

■  Apple  II:  A  general  reference  to  the  Apple  II  family  of 
computers.  It  includes  the  Apple  II,  Apple  II  Plus,  Apple  lie, 
Apple  He,  and  Apple  IIGS. 

■  standard  Apple  II:  Any  Apple  II  computer  that  is  nol  an  Apple 
IIGS.  Because  previous  members  of  the  Apple  II  family  share 
many  characteristics,  it  is  useful  to  distinguish  them  as  a  group 
from  the  Apple  IICS,  A  standard  Apple  II  may  also  be  called  an 
8-bU  Apple  11,  because  of  the  8-bit  registers  in  its  6502  or  65C02 
microprocessor. 
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Typographic  conventions  ~  ' 

Each  new  term  introduced  in  this  book  is  printed  in  bold  type 
where  it  is  first  defined.  That  lets  you  know  thai  the  term  has  not 
been  defined  earlier,  and  also  indicates  that  there  is  an  entry  for 
it  in  the  glossary. 

Assembly-language  labels,  entry  points,  program  and  subroutine 
names,  and  filenames  that  appear  in  text  passages  are  printed  in  a 
special  typeface  {for  example,  DoWItem  and  MENU  .  PAS).  There 
is  one  exception:  the  names  of  Apple  IlCS  system  software  rouLinesi 
such  as  toolbox  calls  and  operating  system  calls  (for  example, 
KewModalDialog  and  QUIT),  are  printed  in  normal  type. 

<•  A'ofe.-  The  source- code  listings  of  the  program  HodgePodge 
follow  a  different,  special  typographic  convention.  See  "Code- 
Lisling  Convention"  in  Chapter  2. 


Watch  fof  these 

The  following  words  mark  special  messages  to  you; 

❖  No!0:  Text  set  off  in  this  manner  presents  sidelights  or 
interesting  points  of  information. 

Important    Text  set  off  in  this  manner-with  the  word  Important-pr&sents 

impoftaot  Infomnatlon  or  Iretfuctfons. 


Warn  Ing    Text  set  off  In  ttils  manner-wlth  ftie  word  Warning-Indicates 
potential  serious  p:oblems, 
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Apple  liGS  Concepts 


Writing  we  11' designed  programs  for  the  Apple  IIGS  computer  (s 
both  an  adventure  and  i  challenge-  It  may  require  some  changes 
in  the  way  you  approach  programming,  some  changes  that  at  Firsl: 
seem  confusing.  But  don'[  worry-  there  are  tools  and  resources  to 
help  you  at  every  step,  to  maJce  the  shift  in  programming  style 
relatively  easy.  And  fasL 

As  you  start,  you'll  want  to  keep  several  key  concepts  in  mind.  This 
chapter  introduces  those  basic  ideas.  We'll  be  building  on  them 
throughout  the  book,  and  showing  examples  of  them  in  action,  in 
the  sample  program  HodgePodge.  They  include 

□  desktop  appUcaliom — programs  with  a  user  inteface  based  on 
Apple's  Human  Interface  Guidelines 

□  event-driven  programming — creating  the  fundamental  internal 
structure  of  desktop  applications 

a  the  Apple  !!G$  Toolbox — the  extensive  set  of  programming 
routines  that  make  desktop,  event-driven  programming 
practical 

□  segmentation— 'iechn\<3^cs  that  allow  your  programs  to  use 
memory  more  efficiently 

□  dsvelopment^si&^s  to  follow  in  creating  a  running  program 


A  more  powerful  Apple  II 

The  Apple  IIGS  personal  computer  is  a  new  Apple  11  with  many 
high-performance  features.  Some  of  its  highlights  are 

□  a  more  powerful  microprocessor  with  faster  operation  than 
processors  used  in  standard  Apple  11  computers,  and  with  a 
24'bit  address  bus 

□  2S6k  memory,  expandable  to  8  megabytes 

□  high-resolution  RGB  video  display  for  Super  Hi-Res  color 
graphics  and  text 

□  multi-voice  digital  sound  synthesizer 

□  detached  keyboard  with  Apple  Desktop  Bus™  connector 

□  built-in  I/O:  clock,  disk  port,  and  serial  ports  with  AppleTalk® 
interface 

□  slots  and  game  I/O  connectors  compatible  with  standard 
Apple  II  computers 
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❖  Note:  If  you  are  noi  familiar  with  the  Apple  n  family  of 

computers,  you  may  want  to  refer  to  the  Technical  Introduction 
to  the  Apple  IIGS  or  your  Apple  IIGS  Otoner's  Guide  for 
explanations  of  some  of  the  terms  in  this  section. 


Super  Hl-R&s  video 


Detached  keyboard 
Apple  Desktop  Bus 
Mouse  SLippOft 


65cai6  processoi 
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Built-in  AppieToik 
Btiitt-in  i/O  ports 
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Figure  1-1 

Apple  !IGS  features 


A  fd-to/t  processor  handles  data  In 
chunks  of  16  bits  at  □  time,  twice 
as  much  data  per  cycle  as  on 
fl-Wf  processor, 


The  6581 6  microprocessor 

The  microprocessor  in  the  Apple  lIGS  is  a  65SC816,  a  l6'bit 
CMOS  design  based  on  the  6502  processor  used  in  previous 
Apple  II  computers  Among  the  features  of  the  65816  are 

□  ability  to  emulate  6502  and  65C02  3-bit  microprocessors 

□  l6-bjt  accumulator  and  index  registers 


A  more  powerful  Apple  II  3 


stack  and  difsct-page  concepts  □  relocatable  stack  and  direct  pace  (zero  psEe) 
ore  discussed  further  in  Chapter  6.  y^s^  v^>=i  u  pi^cj 

□  24-hii  internal  address  bus,  giving  a  l6-megabvEe  memory 

space 


Two  execution  modes 

The  65816  microprocessor  can  operate  in  two  diJTereni  modes; 
tiadve  mode,  with  all  of  its  new  features,  and  6502  emulation 
mode,  for  running  programs  written  for  standard  C8-bil)  Apple  H 
computers. 

Applications  written  for  the  Apple  lIGS  use  native  mode  with  the 
accumulator  and  index  registers  16  bits  long.  Also,  the  size  of  the 
stack  and  the  locations  of  the  stack  and  direct  page  within  bank 
$00  are  at  the  discretion  of  the  application. 


Two  clock  Speeds 

The  microprocessor  in  the  Apple  IIGS  can  operate  at  either  of  two 
clock  speeds;  the  standard  Apple  II  speed  of  1  MH2,  or  the  faster 
speed  of  2,8  MHz,  When  running  programs  in  RAM  the  Apple  IIGS 
uses  a  few  clock  cycles  for  refreshing  memory,  making  the 
effeciivG  processing  speed  about  2.5  MHz.  SysLera  firmware, 
running  in  ROM,  njns  at  the  full  2.8  MHz. 


the  65816  registers  are  discussed 
in  more  detoil  In  thg  Apple  IIGS 
Hardware  Rstsrence. 


Tfonstormable  registers 

If  you  are  an  assembly-language  programmer,  note  from  Figure 
1-2  how  the  processor's  registers  change  size  to  accommodate 
mode  changes.  The  accumulator  and  X-  and  Y-index  registers 
change  from  8  bits  to  16  bits  in  going  from  emulation  to  native 
mode.  The  stack  pointer  also  becomes  16  bits  long,  meaning  that 
in  native  mode  the  stack  can  be  anywhere  in  bank  $00;  in 
emulation  mode  it  is  confined  to  page  1  of  bank  $00,  The  direci 
register  is  not  used  in  emulation  mode;  in  native  mode  it  is  the 
base  address  for  all  zero  page  addressing  modes,  meaning  that  in 
native  mode  the  Apple  IIGS  can  have  several  zero  pages  (called 
direci  pages),  located  anywhere  in  bank  SOO. 
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Figure  1  -2 

Program  registers  in  the  6Sal6  microprocessor 
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For  odditionol  memory  concepts, 
see  Chapter  6  of  ttiij  book  For 
more  cornpiete  information,  reod 
ttis  rQchnicaf  Introduction  ta  the 
Appis  tKss. 


Expanded  memory 

Thanks  lo  Ihc  24-bit  addresses  of  the  65816,  the  Apple  IIGS  can 
access  a  total  mernory  space  of  l6  iriegabytes.  Of  this  total,  up  to  S 
megabytes  of  memory  is  available  for  RAM  expansion,  and  one 
megabyte  is  available  for  ROM  expansion.  The  rest  is  not  used. 

The  minimum  memory  con flgu ration  for  the  Apple  IIGS  is.  256K 
of  RAN!.  Programs  written  for  the  Apple  IIGS — that  is,  programs 
that  run  the  65816  microprocessor  in  native  mode  (thereby 
gaining  the  ability  to  address  more  than  64K  of  memory)— can 
use  up  10  about  176K  of  the  256K.  The  rest  is  reserved  for  displays 
and  for  use  by  the  system  firmware. 

*  A'o/e.-  If  your  application  uses  the  Apple  IIGS  Toolbox — as  this 
book  strongly  recommends — your  application  will  have  less 
than  176k  of  available  space  on  a  256K  machine.  So  if  you  are 
writing  anything  other  than  a  very  small  program,  the  program 
will  probably  require  an  Apple  IIGS  with  a  minimum  of  51 2K  of 
RAM, 
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Figure  1  -3 

Apple  IIgs  memory  map 


For  more  Information  on  the 
memory  configuration  of 
standard  Apple  II  computers,  see 
the  Apple  tie  Technical 
Reference  MonuoJor  Apple  Itc 
Technical  RefefOr-ice  Manual. 


The  basic  256K  of  RAM  memory  is  mapped  as  four  banks  ($00, 
$01,  $E0,  and  SEl)  of  64K  each.  As  Figure  1-3  shows,  portioas  of 
Ihose  banks  are  reserved  for  system  use  or  L/O  addresses,  just  as 
in  other  Apple  II  computers. 

The  Apple  IIGS  has  a  special  card  slot  dedicated  to  memory 
expansion,  All  the  RAM  on  an  Apple  IIGS  memory  expansion 
card  is  available  for  Apple  IIGS  application  programs.  Expansion 
memory  is  contiguous;  its  address  space  extends  without  a  break 
through  all  the  ItAM  on  the  card.  Expansion  RAM  on  the 
Apple  IIGS  is  not  limited  to  use  as  data  storage;  program  code  can 
run  in  any  part  of  RAM. 


Super  Hi' Res  video  display 

The  Apple  IIGS  gives  you  the  most  sophisticated  high-resolution 
color  display  of  any  member  of  the  Apple  II  family.  Now  your 
applications  can  mix  dazzling  color  and  sharp,  SO-coIumn  text  or 
precise  hne  drawings  on  the  same  screen.  And  do  it  easily,  with 
the  help  of  built-in  toolbox  routines. 
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Hi'Res.  Double  Hl-Res,  and  other 
standard-Apple  II  video  display 
(Tiodes  are  described  in  Itie 
Apple  Il9  TBChnlcal  Refetenca 
Manual  arid  Apple  lie  Technical 
Referencs  Manual. 


In  addition  lo  ali  the  video  display  modes  of  ihc  Apple  lie  and 
Apple  He,  the  Apple  IIGS  has  two  new  Super  Hi-Res  display  modes 
that  look  much  clearer  than  standard  Hi-Res  and  Double  Hi-Res. 
Super  Hi-Res  is  also  easier  lo  program  than  Hi-Res  or  Double  Hi- 
Res,  because  it  maps  entire  bytes  onto  the  screen,  instead  of  seven 
bits,  and  because  its  memory  map  is  linear. 

Used  with  an  analog  RGB  video  monitor,  the  Apple  IIGS  displays 
high-quality,  high-resolution  color  graphics.  Table  1-1  lists  the 
specifications  of  the  two  new  graphics  modes. 


Toble  1-1 

Super  Hl-Res  graphics  modes 


Mod* 


320 
640 


Horlzor^tal 
rasolutlon 


320 

640 


VarMcal 
[esolution 


200 
200 


Bit»  Fwr 
pixel 


4  bits 
2  bits 


Colors 
p«r  lln# 


16 
16- 


Cotori 
on  screen 


Colors 
l^osslble 


256 
256* 


4096 


♦Different  pixels  in  640  mode  use  different  subsets  of  the  available  colors. 


PiMl  [s  short  (or  picture  element.  A 
pixel  corresponds  to  the  smallest 
dot  you  can  draw  on  ttie  screen. 


For  rtiore  Informoflon  on  using 
coloi,  see  *  Drawing  to  the 
Sareen'  In  Chapter  3. 


Each  dot  on  the  Super  Hi-Res  screen  is  a  pixel.  The  screen  image 
is  either  320  pixels  or  640  pixels  across,  by  200  pixels  down,  In 
memory,  each  pixel  has  either  a  2-bit  (640  mode)  or  a  4-bit  (320 
mode)  value  associated  with  it.  The  pixel  values  select  colors  from 
programmable  color  tables.  A  color  table  consists  of  16  entries, 
and  each  entry  is  a  12-bit  value  specifying  one  of  4096  possible 
colors. 

in  320  mode,  each  pixel  consists  of  four  bits,  so  it  can  select  any 
one  of  the  l6  colors  in  a  color  table.  Its  palette  is  all  l6  colors  in 
the  color  table.  In  640  mode,  each  pixel  is  only  two  bits,  so  it  can 
select  from  four  colors  only.  However,  the  640-mode  color  table  is 
divided  into  four  mini-palettes  of  four  colors  each,  and  successive 
pixels  select  from  successive  groups  of  four  colors.  Thus,  even 
though  a  given  pixel  in  640  mode  can  be  one  of  only  four  colors, 
different  pixels  in  a  line  can  take  on  any  of  the  colors  in  a  color 
table. 

To  further  increase  the  number  of  colors  available  on  the  display, 
there  can  be  up  to  16  different  color  tables  in  use  at  the  same 
time,  giving  as  many  as  256  different  colors  on  the  screen. 
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(^■Q  jto  5-^  Eho\vis  -the  mqjo/ 
components  o'  the  sound 
hafoJuva'a, 


for  rn Ore  iri formation  nn  L.^hg 
'sDund,  E.&S  the  section,  "h/oking 
Sounds'  In  Cnaptor  G.  $^  alio 
1hi3t  /ippto  lies  Hord\i\^{e 
licference  to  '.  detoils  aboui  I  he 
■sound  system  and  1he  DCC. 


DigifctI  sound  synthesizer  ^ 

Likf;  Q\.hGT  computers  in  the  Apple  H  family,  the  Apple  IlGS  can 
produce  simple,  $in;^le-bil:  sounds  suoh  ms  tilitik.s,  bt:ci>s,  and  tynes,-^ 

But  it  can  slIko      a  whole  foC  more.  'I'he  Apple  IIGS  has  a  new 
dij^ila!  sampling  sound  system  builc  around  a  special-puipoac 
synthesiser  IC  called  the  Digital  OsdllaUjr  Chip,  or  nOC  for 
short.  V.aing  ilii;  DOC,  the  Apple  llGS  can  produce  15- voice  music 
and  olber  complex  sounds  wilJbout  tyin^  up  its  main  prrjccs:iOr. 

Tlie  soujrd  system  consisK  of  ihc.  DOC,  an  audio  amplifier  and 
intecr^al  sjx'iiikcr,  a  connector  for  an  external  amplifier  and 
Kpeakfsr,  64K  of  independent  RAM  for  siorase  of  sound  samples, 
and  a  custom  IC  called  the  Sound  GLU  Cgcneral  logir  unii),  'I tic 
Sound  GLU  is  the  system  ititcrfatxj  to  Ihfj  DOCj  and  also  controls 
tho  vfihimc  oP  ibe  old-style  single -bit  output.  j 


l  or  mors  information  cn  using  tbs 
Apple  Desktop  Bus.  soo 
'Commuriicatiig  wirn  Flies  o.'id 
DoVioes'  in  Choprer  b.  ass  olso 
the  AppSa  !iss  Tonlhme  Qefersnco 


D#t^ctied  keyboard  with  Apple  Desktop  Bus 

The  new  .detached  keyboard  includes  cursor  kt^ys  -^nd  a  numeric 
keypad.  Tire  Applt;  Dfi.sktt.Ji.5  Bus,  which  supports  the  keyboard  and; 
ilic.  Apple  Mouse,  can  also  handle  other  input  devices  sucli  api. 
joysticks  and  graphics  tablets. 


Expansion  slots  and  built-in  I/O 


Tn  addition  to  tlit;  nu-:mory  expansion  slot  mentioned  earlier,  tire 
Appk:  Ilf'.S  has  seven  I/O  expansion  slots  like  tliose  on  an  Apple 
Ue.  Most  peripheral  card*;  desigocd  for  ]hi.:  Apple  II  Ifliis  and  the 
Apple  He  work  in  tljc^  Apple  NGS  slots.  I'he  Apple  I  ICS  also  has 
gaint:  I/Q  connectors  for  joysiicks  and  otfver  game  hardw:irt:. 

Like  the  Apple  lie,  the  Apple  UGS  has  one  built-in  disk  port  and 
iwo  serial  7/0  |;orl«.  'Ilie  built-in  AppleTalk  intejiace  uses  ooc  of 
tti;:  serial  ports.  Programs  can  use  eStho!'  the  buill-in  ports  or 
peripheral  cards  in  sloLs  to  pcrfnrm  input/output  functions. 
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Bulk-ift  I/O  feanjiie$  are  accessed  as  though  they  were  peripheral 
csidsi  in  slots.  Fci  most  of  the  expansion  slots,  [he  user  can 
choose  Con  the  Control  t'anel)  belween  using  a  ix;ri[ili(.:rAl  t:ard  or 
using  the  buifi-in  feature  ^isstxiated  with  the  slot  Isble  1-2  shows 
tlm  ,sl!;t-<:rjuivalcnLs  for  tlie  bulk-in  fealures, 

Tabfe  1-2 

Appio  IJge  ciq:xjnE3on  slots  and  fntefnal-port  equivalents 

Slot        Availoblfl  mlvrnal  SbqIuth 

1  st:ri'jl  [)(iirl  (^[irinliir) 

i  Kt^ri^l  pint  ((.-fmimurii^Jilioii.s) 

5  fiO-cohjiiin  ilisf  iby  ftrtriwafc 

$:  SlimilPlJfl  (disk  ,SU[lJH>fO 

T)|isl<  MJpjHWl 

7  Applc'I'alk  support 


Clock-calendar  and  Control  Panel 

"Ihe  Appk  lies  has  a  builHn  rciUime  dork.  'I'lstj  uwer  wi.s  lh<: 
lime  and  date  wilti  the  Contro!  Panel,  a  ROM  based  proj^r^im  thnt 
al.S[j  ajiifiyLirtis  Lrxpjiiisitin  ^loLi,  st:rial  poiL-i,  displny  iioIotm,  sound 
volume  and  piich,  and  other  option.? 

All  Conlrol  Panel  fellings,  including  the  ciock -calendar  values,  are 
mainiiined  in  a.  specsai  batEcry-powered  RAM  ±aic  is  maintained 
i-vi'.n  dunng  power  fnicrn.jpfions 


Compafibllih/  with  standard  AppI^  M  computers 

Although  the  Apple  IIGS  is  more  powerful  than  previous  Apple  II 
computeis,  it  is  still  s.  ji^esiibcr  of  the  family,  Wstli  the 
microproce.S5-or  sn  6502  emulation  mode,  and  with  the  Pror>OS  S 
Operating  system  acii-ve,  nearly  any  ProDOS-8-based  Apple  II 
application  runs  just  fine  on  the  Apple  IIGS.  The  only  noticeable 
dilTcrcntx  i.'v  :i  2.5'iimefi  inrffiaise  in  f.xerntifjn  .sprjcd- — anil  v.vr.n 
that  difference  can  be  eliminated  if  your  software  muse  run  ac  the 
6502  clock  speed,  Furthemioiie,  as  just  noted,  most;  peripheral 
v.nnhi  tlKsigned  Tor  ibe  Apple  11  t'lijs  or  Apple  Me  will  ftjnction 
identically  in  the  Apple  I  ICS, 
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ProI>OS  16isths  Apple  liGS  disk 
operating  sirfem.  It  is 
documented  In  Itis  Apple  tkss 
ProDOS  16  Referonca  See  also 
Chopter  6  of  this  book. 


Getting  the  most  out  of  the  Apple  IIGS,  however,  requires 
execution  in  65816  native  mode  under  the  more  advanced 
ProDOS  16  operating  system.  That's  what  this  book  is  about: 
writing  programs  that  take  full  advantage  of  the  computer.  Under 
those  conditions,  existing  standard-Apple  II  applications  cannot 
run  without  at  least  some  modification.  If  you  have  written  a 
standard-Apple  II  application,  see  Appendix  D  for  suggestions  on] 
how  to  modify  it  for  native- mode  operation  under  ProDOS  l6. 


The  Apple  desktop  interface 

Desktop  applications  are  programs  of  a  particular  .style^ — a  style 
that  presents  an  accessible,  nonthreatening,  and  predictably 
consistent  interface  to  the  user.  If  your  programs  show  these 
qualities,  they  will  be  easier  to  learn  and  more  satisfying  to  use. 

The  concepts  behind  this  style  of  program  constitute  the  Apple 
Human  Inter/ace  Guidelines.  This  section  will  help  you  see  what's 
involved  in  writing  an  application  that  follows  the  guidelines. 

Figure  1-^  shows  some  of  the  common  visual  features  of  a  desktop 
application.  The  interface  is  graphics-based  rather  than  text-bas&d. 
The  screen  itself  represents  the  desktop,  upon  which  documents 
appear  in  movable,  scrollable,  overlapping  windows-  Pull-down 
menus  appear  across  the  top  of  the  desktop.  Icons  instead  of  text 
may  represent  certain  concepts  or  objects,  The  user  can 
manipulate  the  menus,  icons,  windows,  and  window  contents  with  % 
mouse  or  other  pointing  device  as  well  as  with  the  keyboard. 
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These  visual  features  are  not  the  real  essence  of  a  desktop 
application,  however.  The  true  importance  of  desktop  applications 
!ies  in  their  relationship  with  the  user,  as  explained  next. 


Human  Interface  Guidelines 

If  you  are  developing  application  programs  for  the  Apple  IIGS 
computer,  you  are  strongly  encouraged  to  follow  the  principles 
presented  in  Human  Inler/acs  Guidelines:  The  Apple  Desktop 
Interface.  That  manual  describes  the  desktop  interface  through 
which  the  computer  user  communicates  with  the  computer  and 
the  applications  running  on  it.  This  section  briefly  outlines  a  few 
of  the  human  interface  concepts.  The  Apple  Desktop  Interface, 
first  introduced  with  the  Macintosh  computer,  is  designed  to 
appeal  to  a  nontechnical  audience.  Whatever  the  purpose  or 
structure  of  your  application,  it  will  communicate  with  the  user  in 
a  consistent,  standard,  and  nonlhreatening  manner  if  it  adheres  to 
the  desktop  interface  standards.  These  are  some  of  the  basic 
principle.?: 

■  Human  control.-  Users  should  feel  that  they  are  controlling  the 
program,  rather  than  the  reverse.  Give  them  dear  alternatives 
to  select  from,  and  act  on  their  selections  consistently. 
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■  Dialog;  There  should  be  a  dear  and  friendly  dialog  between 
human  and  computer,  Make  messages  and  requests  ta  the  user 
in  plain  English. 

■  Direct  manipulation  and  feedback:  The  user's  physical  actions 
should  produce  physical  results.  When  a  kc>'  is  pressed,  place 
the  corresponding  letter  on  the  screen.  Use  highlighting, 
animation,  and  dialog  boxes  lo  show  users  the  possible  action! 
and  their  consequences, 

■  See-and-polnt  (instead  of  reniembef-and-type>  The  user  select 
actions  from  alternatives  presented  on  the  screen.  In  general, 
the  process  is  in  the  order  object  followed  by  mrb—ih^i  is 
one  selects  first  the  object  lo  be  acted  upon,  and  then  the  ' 
action  to  be  performed.  g 

■  ExpIoraUon:  Give  the  user  permission  to  test  out  the 
possibilities  of  the  program  without  worrying  about  negative 
consequences.  Keep  error  messages  infrequent.  Warn  the  user 
when  risky  situaUons  are  approached,  but  don't  erect 
unnecessary  barriers. 

■  Graphic  design?  Good  graphic  design  is  a  key  feature  of  the 
guidelines.  Objects  on  the  screen  should  be  simple  and  clear 
and  they  should  have  visual  fidelity  (that  is,  they  should  look' 
Ijke  what  they  represent).  Use  familiar,  concrete  metaphors  to 
represent  aspects  of  the  computer  and  program.  The  desktop  is 
the  primary  metaphor  in  the  Apple  Desktop  Interface. 

■  Avoiding  modes:  A  mode  is  a  portion  of  an  application  that 
the  user  must  explicitly  enter  and  leave,  and  that  resuncts  the 
operations  that  can  be  performed  while  the  mode  is  in  effect 
By  restricting  the  user's  options,  modes  reinforce  the  idea  that 
computers  are  unnatural  and  unfriendly.  Use  modes  sparingly. 

■  Device-independence:  Make  your  program  as  hardware- 
independent  as  possible.  Don't  bypa.ss  the  system-provided 
sofn^are  tool  sets  and  inierface^your  program  may  become 
incompatible  with  future  products  and  features.  | 

■  Consistency:  As  much  as  possible,  all  your  applications  should 
use  the  same  interface.  Don't  confuse  the  user  with  a  different 
look  for  each  program. 

■  Evolution:  Consistency  does  not  mean  that  you  are  restricted  to 
using  existing  desktop  features.  New  ideas  are  essential  for  the 
evoluuon  of  the  Human  Interface  concept,  If  your  application 
has  a  feature  that  is  not  described  in  Human  Interface 
Guidelines,  make  sure  it  cannot  be  confused  with  an  existing 
feature,  it  is  better  to  do  something  completely  different  than 
to  half-agree  with  the  guidelines. 
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Why  write  desktop  applications? 

The  biggest  reason  for  programming  desktop  applications  on  the 
Apple  IIG5  is  the  cofLsisient  interface  they  present.  Users  spend 
less  Lime  learning  and  more  lime  using  an  application  if  they 
already  know  their  way  around. 

There  are  some  disadvantages  to  desktop  applications.  Apple  IIG5 
desktop  programs  will  oat  mn  on  the  Apple  He  and  lie.  Because 
desktop  applications  require  the  use  of  graphics  to  support 
windows  and  multiple  Tonts,  the  interface  can  be  slower  than  a 
simpler  text-based  command-line  or  menu  interface.  Also  it  takes 
time  to  learn  the  techniques  of  writing  desktop  applications. 

On  the  other  hand,  experience  with  the  Apple  Macintosh 
computer  has  shown  that  an  interface  that  is  consistent  from  one 
application  to  another  is  extremely  attractive  to  users,  because  it 
dramatically  cuts  down  the  learning  time  for  each  new 
application.  The  Apple  desktop  and  the  Human  Interface 
Guidelines  have  been  refined  over  several  years  of  studies  and 
first-hand  experience  by  Apple  and  independent  developers. 

The  cost  to  you  in  development  time  is  minor  when  you  consider 
the  increase  in  your  product's  appeal  due  to  ease  of  use  and 
compatibility  with  the  Macintosh  interface.  In  addition,  if  you  are 
an  Apple  II  developer  new  to  the  Apple  desktop,  the  techniques 
you  leam  (although  not  the  actual  code,  in  most  instances)  are 
directly  applicable  to  the  Macintosh. 


ApDsndix  B  discusses  how  writing 
Apple  lies  desktop  applications 
diffafs  ffom  programming  for 
standard  Apple  II  computers- 


Appendlx  A  discusses  how  writing 
Apple  liGS  desktop  opplicotlons 
dittos  from  Macintosh 
progpammlng. 


Event-driven  programming 

In  the  old  days  of  programming,  all  programs  were  executed  in 
batch  mode;  the  entire  program  was  put  on  computer  cards  (or 
worse,  punched  paper  tape)  and  fed  into  the  computer  all  at  once 
The  computer  executed  the  instructions  in  the  same  sequence 
every  lime  the  program  was  run  (any  conditional  branching  was 
controlled  by  data  read  in  with  the  program),  reading  data  and 
writing  out  results  at  specified  points  in  the  program. 

Batch  mode  was  fine  for  "crunching  data",  but  it  wasn't  very  useful 
for  applications  (such  as  word  processing  or  drawing)  that  require 
the  user  to  make  decisions  while  the  program  is  running.  When 
computer  terminals  were  invented,  programmers  began  writing 
programs  that  allowed  users  to  send  commands  to  the  computer 
and  wait  for  responses — interactive  programs  were  born. 
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An  av9nt  Es  q  notiflcolion  to  Itie 
QppllcQtion  of  some  occurrence, 
InTornol  or  external,  to  wt\lch  the 
application  moy  choose  to 
t^espond. 


Any  interaclive  program  is  in  some  sense  event-driven.  That  is, 
the  computer  spends  much  of  its  time  waiting  for  some  user  input 
to  occur,  usually  a  l^ey  press.  Traditional  interactive  programs, 
however,  still  largely  control  the  choices  and  the  sequence  in 
which  operations  are  performed.  The  user,  who  follows  rather 
than  leads,  still  feels  that  the  program  is  in  control. 

With  the  introduction  of  the  Apple  Macintosh  and  Lisa® 
computers,  Apple's  Human  Interface  Guidelines  and  event-driven 
programming  came  into  prominence.  The  basic  principle  of 
event-driven  programming  is  that  there  are  many  choices 
available  at  any  time,  and  that  the  user  controls  the  flow  of  the 
program.  In  a  typical  Apple  I  ICS  program,  for  example,  the  user 
can  select  choices  from  a  half-dozen  menus,  open  or  dose 
windows,  use  desk  accessories,  resize  or  move  windows,  or  do 
some  sort  of  work  (such  as  word  processing  or  drawing).  With  few 
exceptions,  any  of  these  operations  is  available  at  any  given  time, 

Events  that  cause  a  response  by  the  program  include  key  presses 
and  mouse-button  clicks,  and  might  also  include  use  of  game 
paddles,  insertion  of  a  disk  in  a  disk  drive,  data  coming  over  a 
communication  line,  or  even  events  generated  by  the  program 
itself,  I 


The  main  event  loop 

Although  an  event-driven  program  may  at  first  appear  extremely 
complex,  its  basic  structure  is  actually  quite  simple,  It  spends  most 
of  its  time  waiting  in  a  program  loop  called  the  main  event  loop. 
The  only  thing  the  program  is  waiting  for  is  an  event^ — any  event 
When  it  detects  an  event,  it  determines  the  type  of  event,  takes 
whatever  action  is  necessary,  and  returns  to  the  main  event  loop 
to  wait  for  ]i\e  next  event. 

Figure  1-5  is  a  conceptual  representation  of  the  flow  of  execution 
in  an  event-driven  program,  For  most  of  the  time,  the  taxi 
Cprogram  execution)  remains  in  the  event  loop,  circulating 
constantly,  and  slopping  at  the  taxi  stand  (the  event  queue)  each 
time  to  see  if  there  is  a  waiting  passenger  (an  event).  The  taxi  takes 
passengers  in  order,  one  at  a  time,  to  their  respective  destinations 
(various  event-handling  subroutines),  Tlie  taxi  waits  out  front  while 
the  event  is  being  handled  (execution  temporarily  leaves  the 
event  loop),  then  proceeds  around  the  loop  once  more  to  pick  up 
another  passenger.  Circulation  continues  until  the  program  ends. 
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Figure  1  -S 

The  nrain  event  loop 

For  a  more  specific  example,  assume  that  the  program  is  a  word 
processor.  From  ihe  user's  point  of  view,  any  of  a  large  number  of 
operations  are  available,  from  typing  a  characser  to  reformatting 
the  entire  document  to  setting  control-panel  options.  The  main 
event  loop,  however,  need  wall  for  only  two  types  of  events: 
mouse-button-down  and  key-down. 


Event  handling 

To  illustrate  how  a  program  handles  an  event,  let's  suppose  that 
the  user  decides  to  select  an  item  In  a  window  titled  CORTIAND 
Csee,  for  example,  Figure        that  is  open  on  the  screen  but  not 
currently  active.  The  user  moves  the  mouse  to  the  inactive  window 
and  dicks  the  mouse  button.  When  the  program  detects  the  event, 
it  handles  it  like  this; 
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1.  What  kind  of  event  was  it  Cmouse-down,  key^down  and  so 
forth)? 

Mouse-down 

CAt  this  point  execution  leaves  the  main  event  loop  to  handle 
the  event.) 

Z  Was  it  in  a  window,  on  Uie  menu  bar,  or  neither? 
Window 

3-  Was  it  the  active  window  or  an  inactive  window? 

InacHvs 
4  which  inactive  window? 

CORTLAND 

5,  Make  CORTLAND  the  active  window. 

6.  Return  to  the  main  event  loop, 

Why  return  to  the  main  event  loop  now  instead  of  going  to  a  loop 
that  can  handle  events  that  can  occur  only  within  the  acUve 
window?  Because  the  user  might  change  his  mind  and  decide  to 
open  a  menu,  select  a  different  window,  or  even  quit  the  program. 
If  you  return  to  tfre  main  event  loop  as  soon  as  possible,  the  user 
retains  the  feeling  of  being  in  conwol  of  the  program. 

The  structure  of  an  event-driven  program  can  be  fundamentally 
different  from  that  of  other  types  of  applications.  Its  principal 
subroutines  are  organized  by  events  to  handle  ("mouse-down  " 
"key-down'),  rather  than  by  the  specific  tasks  the  program  was 
written  to  perform  Ctext  entry,"  "drawing").  Chapter  2  illustrates 
this  difference  in  detail. 

The  Apple  IIGs  provides  a  large  number  of  software  tools  that 
make  it  easier  for  you  to  write  an  event-driven  program.  The 
Event  Manager  performs  the  bookkeeping  that  makes  your 
program's  main  event  loop  work— it  gathers  events,  determines 
T   r,.   .    ,  ^yP^^>  3nd  places  them  in  order,  for  vour  orooram  m 

g^M^t.  is  oescHbed  ,n  handle.  A  too.bo.  routine  called  Ta.kMaslZZ:!::Z^  takes 

care  of  Simple  event-handling  such  as  resizing  or  moving  a 
window.  Then  ii  passes  the  information  on  to  your  program. 

Wll  look  at  events  in  much  greater  detail  as  we  go  along.  Chapters 
2  through  5  describe  the  sequence  of  tool  calls  and  procedures  that 
an  event-driven  program  must  execute  on  the  Apple  IIGS  and 
Appendixes  E  through  G  present  source  code  for  such  a  program  in 
mree  different  programming  languages  (assembly  language,  C,  and 
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The  Apple  liGS  Toolbox 

Trying  to  write  a  desktop,  event-driven  application  wiihoui  the  aid. 
of  some  powerful  system  software  could  be  quite  difficult. 
Fortunately,  the  Apple  IlGS  comes  equipped  with  a  software 
toolbox,  which  contains  a  complete  complement  of  lool  sets 
designed  to  make  your  job  easier. 

Manet  too; se/ are  The  Apple  IIGS  tools  support  tlie  standard  desktop  interface  and 

synonymous.  provide  you  with  building  blocks  to  help  you  construct  your 

application. 


Pen  SzQ  and  pen  mode  are 
discussed  under  'Drowing  to  the 
Scram.'  In  Chapter  3. 


Manager\s  simply  another  name 
ifX  tool  set. 


What  is  a  tool  set? 

A  tool  set  in  the  Apple  IlGS  environment  is  a  collection  of 
related  software  routines  that  provides  one  major  capability.  Kach 
routine  within  a  tool  set  performs  a  fundamental  operation.  For 
example,  the  QuickDraw  II  tool  set  provides  routines  that  handle 
graphics  on  the  Apple  IIGS.  Within  QuickDraw  II,  SetPenSize  and 
SetPenNlode  are  routines  that  set  the  pen  size  and  pen  mode.  A 
routine  may  take  one  or  more  specific  parameters  as  input  and 
yield  one  or  more  values  as  output. 

The  tool  sets,  then,  are  groups  of  related  routines  that  perform 
many  common  tasks  and  are  always  available  for  your 
application's  use.  Taken  together,  the  tool  sets  are  very  similar  to 
the  Macintosh  toolbox.  Many  of  the  capabilities  of  the  Apple  IIGS, 
even  those  not  directly  related  to  desktop  applications,  are  easily 
accessed  through  Ihe  tools.  For  example,  both  the  Memory 
Manager  (which  allocates  all  Apple  IIGS  memory)  and  the  Event 
Manager  (which  controls  event-driven  programs)  are  tool  sets. 
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You  con  even  use  flie  Tool 
Locator  to  access  a  tool  set  vou 
hove  wrftten  yourself,  Sea  "User 
Tool  Sets*  in  Chapter  8, 


Making  use  of  :cxj1  sets  allows  you  to  concentrate  on  your 
application's  specific  business  rather  than  on  background  work. 

A  number  of  ihc  tools  are  in  ROM  They  arc  [fierefore  available  td 
all  prograrns  without  using  disk  space.  Additional  tools  are 
available  in  RAM,  but  you  needn't  worry  about  where  a  panJcuIai 
tool  set  Of  routine  is.  A  tool  set  called  the  Tool  Locator,  which 
enables  tool  sets  and  applications  to  communicate,  takes  care  of 
the  necessary  bookkeeping  functions.  All  you  need  to  know  is  the 
name  of  the  routine  and  how  to  call  it  in  your  programming 
language. 

Tool  sets  insulate  your  program  from  the  details  of  machine 
hardware.  If  the  program  accesses  a  hardware  feature  with  a  tool 
call,  Lfic  program  will  remain  compatible  through  future  versions 
of  the  Apple  HQS,  ever  if  the  hardware  feature  changes. 

The  tools  thus  provide  an  abundance  of  capabilities  at  a 
minimum  cost  in  programming  time  and  memory  space.  Their 
bookkeeping  functions  are  almost  automatic,  the  interface  to  theiri 
is  simple,  and  the  applications  you  write  will  not  be  rendered 
obsolete  by  future  changes  to  the  hardware. 

❖  Note:  Many  of  the  Apple  liGS  tool  sets  are  independent  of  the 
operating  system.  They  are  thus  available  for  any  Apple  IIGS 
application,  regardless  of  the  operating  system  it  is  written  for, 

To  get  an  idea  of  the  range  of  capabilities  of  the  Apple  IIGS 
Toolbox,  it's  useful  to  group  the  tool  sets  into  categories.  The 
arrangement  given  in  Figure  1-6  is  arbitrary;  as  you  get  lo  know  iha 
tools  better,  you  may  prefer  other  groupings. 

Brief  explanations  of  the  tool  sets  within  each  category  follow.  The 
tool  sets  are  described  in  more  detail  ix\  Chapters  3  through  6, 
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The  rive  banc  Desktop  ■  inlerf  ac  alool  s«t$ 


D*ylc«-(n(a'rfacQ'  Operating -envtronment  Speeiallzed  tool  »tt 

tool  »t9  tool  setf. 


Figure  1-A 

Apple  liss  tool  sets 
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The  five  basic  tool  sets 

The  five  tool  SGLs  listed  below  provide  the  framework  upon  whidl 
the  other  tools  can  build.  All  of  these  tool  sets  must  be  used  in 
every  event-driven  application; 

■  Tool  Locator;  Handles  all  tool  calls.  This  tool  set  relieves  you 
of  having  to  know  where  in  memory  any  tools  resides;  the  Tool 
Locator  finds  and  passes  execution  to  the  proper  routine  when 
you  make  a  tool  call  Once  you  start  the  Tool  Locator,  its 
operation  is  automatic. 

■  Memory  Manager;  Allocates  memory  for  use  by  the 

application.  When  your  application  needs  memory,  it  must 
request  it  from  the  Memory  Manager. 

■  Miscellaneous  Tool  Set  Includes  mostly  system-level  routines 
that  must  be  available  for  other  tool  sets  to  use. 

■  QuickDraw  H;  Controls  the  graphics  environment  and  draws 
basic  graphic  objects  arid  text  on  the  screen.  QuickDraw  n 
Auxiliary  is  an  extension  to  QuickDraw  II.  Other  too!  sets  call 
QuickDraw  II  and  QuickDraw  H  Auxiliary  to  draw  such  things  iS 
windows  and  icons. 

■  Event  Manager:  Receives  events  as  they  happen,  maintains  a 
queue  of  events,  and  passes  events  on  to  the  application. 


Desktop -interface  tool  sets  | 

Tools  in  this  group  support  the  desktop  interface.  You  will  almost 

always  use  the  Window  Manager  and  Menu  Manager  in  desktop 

programs;  you  should  use  the  other  tool  sets  if  your  application 

needs  iheir  features  (for  example,  you  need  the  Dialog  Manager  If 

your  application  uses  dialog  boxes).  Many  of  these  tools  are  also 

The  list  or  tool  sets  needed  to  needed  to  support  desk  accessories, 

support  desk  accessories  Is  given 

In  Table  8-1.  ■  Window  Manager;  Creates  and  updates  windows,  keeps  track  d 

size  changes  and  overlapping. 

■  Control  Manager:  Implements  controls — objecte  on  the  screen 
such  as  check  boxes — which  the  user  can  manipulate  with  the 
mouse  to  cause  instant  action  or  to  change  settings. 

■  List  Manager:  Along  with  the  Control  Manager,  handles 
ordering,  display,  and  selection  of  lists  of  selectable  items  in 
windows. 
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■  Dialog  Manager:  Implements  dialog  boxes,  which  your 
application  should  place  on  the  screen  when  it  needs  more 
information  to  carry  out  a  command. 

■  LineEdlt  Tool  Set  Presents  text  on  the  screen  (usually  in  dialog 
boxes),  and  allows  the  user  to  edit  that  text  in  limited  ways. 

■  Menu  Manager:  Controls  and  maintains  pull-down  menus  and 
the  items  in  the  menus, 

■  Font  Manager;  Provides  fonts  in  a  variety  of  sizes  and  styles  for 
QuickDraw  II  to  use  when  it  draws  text, 

■  Scrap  Manager:  Supports  the  desk  scrap,  data  to  be  copied 
from  one  application  to  another  (or  from  one  place  to  another 
within  an  application). 

■  Desk  Manager:  Enables  applications  to  support  desk 
accessories,  mini-applications  that  can  be  run  at  the  same  lime 
as  another  application. 


Device -Interface  tool  sets 

Tools  in  this  group  manage  input  and  output  between  the 
computer  and  peripheral  devices. 

■  Print  Manager:  Carries  out  page-setup  and  printing  commands 
from  the  user.  Provides  an  interface  between  the  application 
and  printer  drivers. 

■  Standard  File  Operations  Tool  Set:  Presents  dialog  boxes  to  the 
user  when  a  file  is  to  be  saved  or  opened.  Provides  a 
standardized  interface  between  the  user  and  ProDOS  16. 

■  Apple  Desktop  Bus  Tool  Set:  Provides  access  to  Apple  Desktop 
Bus  commands.  The  Apple  Desktop  Bus  transmits  signals  to 
and  from  the  keyboard,  mouse,  and  other  input  devices. 

■  Text  Tool  Set:  Allows  applications  running  in  native  mode  to 
access  Apple  II  character  device  drivers,  which  require  the 
processor  to  be  in  emulation  mode. 


The  Apple      Toolbox  21 


J 


Operating-environmenf  tool  sets 

Too]  sets  in  this  group  control  low-level  hardware  and  software 
functions.  The  Memory  Manager  and  the  Miscellaneous  Tool  Set 
listed  under  "The  Five  Basic  Tool  Sets,"  can  also  be  considered 
part  of  this  group.  Other  members  are: 

■  System  Loader:  Loads  all  program  and  data  segments  into 
memory. 

■  Scheduler:  Allows  more  than  one  prograjn  lo  access  system 
resources  that  normally  cannot  be  shared, 


Specialized  tool  sefs 

Tool  sets  in  this  group  perform  various  specialized  functions,  as  ! 
listed. 


Sound  generation 

These  tools  make  it  easy  to  take  advantage  of  the  advanced  s 
capabilities  of  the  Apple  IIGS. 

■  Sourtd  Tool  Set:  Constitutes  the  sound  hardware's  interface  to 
the  Apple  IIGS  Toolbox,  and  provides  basic  sound 
manipulation  routines. 

■  Note  Synthesizer:  Facilitates  creation  of  musical  notes 
simulating  a  variety  of  instruments. 

■  Note  Sequencer:  StJings  together  notes  from  the  synthesizer 
into  the  sequences,  patterns,  and  phrases  that  make  up  a  tune, 


Mathematical  computation 

These  tools  perform  mathemau'cal  functions  and  calculations. 

■  Integer  Math  Tool  Set;  Provides  maihematical  routines  that 
manipulate  integers,  long  integers,  and  signed  fractional 
numbers.  Also  converts  numbers  to  hexadecimal  and  ded 

ASCII  strings. 


i 


SANE  Tool  Set:  Implements  the  Standard  Apple  Numerics 
Environment,  which  provides  extended- precision  floating-pcii 
ariUimetic  that  conforms  to  IEEE  standard  754.  Supports 
multiplication  and  division  and  trigonometric  and  other 
transcendental  functions. 
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Load  111m  are  progianns  In 
mochlne-ejcecutobls  format, See 
fha  Apple  l&S  Ptogsammar's 
WeritiffOp  /Je/erencefof 
hformatlon  on  the  niG  format  (or 
program  segmants. 


See  Vns  Apple  lIGS  RoDOS  16 
ffefefencefor  complete 
Infoimalion  or  ProDOS  16  ond  the 
System  Loader. 


See  Ihs  Apple  llGS  Toolbox 
Refewncefor  complete 
Information  on  the  Memory 
Mcnoaer. 


Program  segmentation 

Anoiher  poiverful  feature  available  lo  Apple  IIGS  programs  is  that 
they  can  be  segmented,  and  the  segments  can  be  relocatable  and 
dynamic.  A  segmented  program  is  divided  into  chunks  that  can 
be  loaded  into  memory  piecemeal.  A  relocatable  segment  is  a 
piece  of  code  or  data  that  needn't  be  put  at  any  particular 
memory  address  in  order  to  function  correctly.  A  dynamic 
segment  is  one  that  is  not  loaded  unLiI  it  is  needed  during 
program  execution, 

Segmeniation  of  executable  programs  (load  flies)  giifes  two 
principal  advaniages:  (1)  your  program  might  fit  into  a  smaller 
memory  space  to  help  it  run  in  small-memory  machines  and 
under  application-switching  programs,  and  (2)  it  might  load  and 
start  to  execute  more  quickly.  Both  advantages  occur  because  less- 
needed  segments  can  be  made  dynamic  and  left  on  tiisk  until  they 
are  actually  called  into  use.  FurLhermore,  on  the  Apple  IICS 
computer  no  single  block  of  code  can  occupy  more  than  64K 
bytes  of  contiguous  memory.  To  load  a  larger  program  than  that, 
you  must  split  it  up  into  two  or  more  load  segments. 

Making  your  load-file  segments  relocatable  means  that  the 
available  memory  in  the  computer  can  be  allocated  efficienUy 
among  multiple  programs  (including  system  software  and  desk 
accessories), 

Segmentation  works  because  the  Apple  1 1 GS  Memory  Manager  and 
System  Loader  tool  sets,  work  together  with  ProDOS  16,  the  Apple 
lies  operating  system,  to  execute,  move,  and  remove  program 
segments  in  a  fashion  that  is  sophisticated  yet  totally  transparent 
to  the  program  user  (and  in  many  cases  to  the  programmer  too). 
The  Memory  Manager  takes  care  of  assigning  each  segment  to  a 
block  of  memory;  the  System  Loader  keeps  track  of  where  in 
memory  the  segment  has  been  loaded,  and  patches  intersegment 
calls  in  each  segment  as  it  is  loaded.  ProDOS  16  controls 
execution  of  the  programs  once  ihey  are  in  memory. 

Chapter  6  presents  a  more  detailed  discussion  of  load-segment 
structure  and  how  the  Memory  Manager,  System  Loader,  and 
ProDOS  l6  interact  to  make  it  all  work. 
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Patching  Is  the  pfocess  of 
modifying  code  once  it  Is  In 
computer  memorv. 


Absolute  and  relocatable  segments 

To  make  efficieni  use  of  memory^  with  segmented  programs,  the 
Memory  Manager  and  System  Loader  need  lo  be  free  to  place 
code  and  data  segments  where  they  choose. 

Absolute  code  is  computer  code  that  must  be  loaded  at  a  specift 
address  in  memory  and  never  moved-  Many  standard  Apple  !I 
programs  contain  absolute  code,  The  programmer  decides  when 
the  program  will  sit  in  memory,  and  designs  all  address 
references  and  subroutine  jumps  accordingly. 

Relocatable  code  is  computet  code  that  contains  relative  and 
symbolic  address  references,  and  so  can  execute  correctly 
wherever  it  is  placed  in  rnemory,  See  Figure  1-7.  Once  it  is  in 
memory,  relocatable  code  must  be  patched  by  the  loader  so  that 
its  address  operands  contain  the  proper  values. 

For  efTtcient  memory  use,  it  is  very  important  that  as  many 
segments  as  possible  be  relocatable,  The  Memory  Manager  must 
be  free  to  place  segments  so  they  will  not  conflict  with  each  other 
and  so  that  contiguous  areas  of  free  memory  are  maximized. 
None  of  your  program's  segments  should  be  absolute. 


S6000  - 


AbsolutG 
segment  can't 
be  loaded; 
onottier  segment 
occupies 
Iqcatlon  54000 


Relocatable 
segment 
fits  in  any 

open  space 
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32000- 


Sxxx>: 


Figure  1  -7 

Absolut©  and  relocatable  segments 
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See  Chapta  6  for  more 
informoMon  on  how  sfatic  and 
dynamic  seainenti  ore  loaded. 


Static  and  dynamic  segments 

A  dynamic  segment  is  a  load  segment  that  can  be  loaded  and  tur 
automatically  during  program  execution,  The  application  itself 
needn'l  do  any  loading — whenever  the  application  calls  a  routine 
that  is  in  a  dynamic  segment,  the  segment  Is  auEomatically  loaded 
and  executed.  Furthermore,  that  dynamic  segment  is  not 
subsequently  unloaded  from  memory  unless  the  application 
pennits  it,  and  even  then  only  when  the  memory  is  needed  for 
something  else;  in  most  cases  the  segment  remains  instantly 
available  the  next  lime  it  is  called. 

A  segment  that  is  not  dynamic  is  static.  A  static  segment  is 
loaded  at  program  startup,  and  is  not  unloaded  or  moved  during 
execution.  The  main  segment  of  any  program  is  static;  any  other 
segments  may  be  static  or  dynamic.  See  Figure  1-8. 

The  question  of  which  segments  to  make  static  and  which  ones  to 
make  dynamic  is  not  as  easily  answered  as  the  question  of 
absolute  and  relocalable.  At  least  one  segment  in  each  program 
must  be  static;  if  the  program  is  small,  that  single  segment  may 
constitute  the  entire  program.  But  if  the  program  is  large  or  if  it  is 
designed  to  require  little  memory,  many  of  its  segments  may  be 
dynamic. 

Making  as  many  segments  dynamic  as  possible  can  also  decrease 
the  time  required  to  initially  load  and  start  up  a  program.  On  the 
other  hand,  there  may  then  be  momentary  delays  during 
execution,  as  the  dynamic  segments  are  loaded  when  called. 


\ 
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Static  ord  dyrtomic  segments 


Program's  main 
(stoflc)  segment 
stays  in  mernory 


Dynomic  segment?  looded  and 
discafded  os  needed 
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The  Programmer's  Workshop 


To  help  you  wriEe  applicalion  programs  that  make  the  most  of  thi 
new  Apple  lIGS  features,  Apple  has  produced  an  integrated 
development  envjronmeni  called  the  Apple  IlGS  Programmer's 
Workshop  CAPW  for  shorO. 

APW  helps  you  create  eveni-driven,  segmented  desktop 
applications  that  access  the  full  power  of  the  Apple  IlGS  Toolbox. 
With  APW  you  can  write  modular  source-code  segments  in  a 
variety  of  high-level  and  low-level  programming  languages,  and 
then  combine  them  into  a  single  fimciioning  program. 

APW's  object  files  and  load  files  follow  a  file  specification  called 
object  module  format  (OMR.  OMF  was  developed,  in  part,  to 
create  i  system  in  which  program  segments  written  in  several 
languages  could  be  combined  and  run  together,  because  they  all 
would  have  one  uniform  object  file  "language ".  With  OMF  you 
can  optimize  various  routines  by  writing  them  in  different 
languages  and  combining  them  into  a  single  program,  A  routine 
written  for  a  program  in  one  language  can  be  dropped  into 
another  program  in  another  language,  without  modification. 

Figure  1-9  is  a  simplified  picture  of  what  lakes  place  from  writing 
to  running  an  application  under  APW. 

1.  A  program  is  first  created  as  a  source  file,  using  a  text  editor 
appropriate  for  the  language(s)  involved.  APW  includes  a  full- 
featured,  multi-language  text  editor.  s 

Z  The  source  file,  in  ASCII  lejtt  form,  is  then  either  compiled  or 
assembled  to  produce  an  object  file.  Directives  in  the  source 
file  control  whether  and  how  ihe  object  file  is  to  be  segmented 
A  single  source  file  can  be  compiled  into  more  than  one 
object  file. 

3.  The  object  file  is  converted  by  a  linker  into  a  load  file. 
Directives  in  the  original  source  file,  as  well  as  commands  to 
the  linker,  can  conuol  segmentation  in  the  load  file.  More  than 
one  object  file  can  be  combined  into  a  single  load  file. 

4.  In  the  final  step  (if  all  goes  well),  the  load  file  runs  correctly  wh( 
the  loader  places  it  in  memory  and  it  is  executed.  In  the  early 
stages,  of  course,  program  development  usually  involves  at  least 
some  time  with  a  debugger  such  as  the  Apple  IlGS  Debugger, 
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An  object  fife  is  a  program  that 
has  passed  through  on 
assembler  or  compiler,  it  contains 
machine-longuage  code. 

Chopter  6  shows  you  how  to 
specify  object  segments  and 


Asource  file  IS  □  progrom  in  Its 
ojlglnai  taxf  form .  as  written  by  ths 
programmer, 


Text  editor 


Assembler/  ^  Object 


compiler  file 


Linker 


Load 
file 


Loadof 


Executable 
code  In 
memofv 


FlgufB  1-9 

Step$  in  creating  an  opplication 

Using  APW  ID  design  and  write  segmented  programs  is  covered  in 
Chapter  7.  But  before  we  get  too  deeply  into  itie  how  of  Apple 
lIGS  programming,  we'd  like  to  show  you  some  more  of  the  what 
and  wby.  The  next  five  chapters  present  an  extensive 
programming  example  and  give  some  additional  background, 
showing  what  Apple  lies  programs  can  do  and  why  they  go  about 
it  in  the  ways  they  do. 


The  Programmer's  Workshop 
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Chapter  2 


Hodgepodge:  A  Sample 
Event-Driven  Application 


f 
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Now  ihat  you've  had  an  overview  of  the  Apple  IIGS  and 
programming  concepts,  let's  plunge  right  into  an  example, 

This  chapter  explores  s  demonstration  application  developed  by 
Apple,  called  HodgePodge.  HodgePodge  has  a  recommended  , 
organization  for  evenE-driven,  desktop  applications  on  the  Apfrffi 
IIGS,  We  walk  you  through  the  program,  presenting  the  code ; 
explaining  it  in  detail  as  we  go  along. 

You  may  wonder  why  we're  dissecting  the  sample  program  so 
soon — after  all,  much  of  its  structure  and  most  of  its  tool  calls  j 
parameters  aren't  explained  until  later  in  the  book.  Our  hope  i 
that,  given  the  general  concepts  already  presented  and  the  i 
sive  commentary  accompanying  these  listings,  your  quickest 
to  understanding  is  to  see  actual  code  from  a  functioning  prog 

On  the  other  hand,  there  is  no  required  reading  order  for  this ! 
book.  If  you  want  to  delve  deeper  into  toolbox  concepts  beforel 
looking  at  code  samples,  by  all  means  skip  ahead  to  Chapters 
through  5-  Come  back  to  this  chapter  when  you're  ready. 

Don't  forget  lo  look  in  Appendixes  E,  F,  and  G  for  the  complen 
source-code  listings  of  HodgePodge  in  all  three  languages 
(assembly  language,  C,  and  Pascal).  And,  whichever  order  you 
read  things  in,  don  e  forget  to  try  HodgePodge  in  action  on  yo 
Apple  IIGSI 


What  Hodgepodge  does 

HodgePodge  is  a  short  application  Uiat  loads  stored  graphic 
images  (picture  files)  from  disk  and  displays  them  in  movable, 
scrollable,  resizeable,  overlapping  windows  on  the  screen.  It  all 
displays,  in  windows,  text  samples  of  the  various  fonts  available  i 
your  system.  See  Figure  2-1. 

Like  a  proper  desktop  application,  HodgePodge  shows  menus, 
displays  messages  in  dialog  boxes,  supports  desk  accessories, 
stores  and  retrieves  files,  prints  texE  and  graphics,  and  even 
provides  an  "About  HodgePodge'  dialog  box  accessible  from 
Apple  menu. 

If  you  have  a  copy  of  the  sample  program,  put  it  in  your  computi 
and  run  it  now.  On  the  disk  that  accompanies  this  book,  it's  the 
application  named  HP,  in  the  folder  for  any  of  the  three  languag 
(There  are  three  files  named  HP — one  for  each  language.) 
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Figure  2-1 

Hodgepodge  desktop 


Hodgepodge's  menus 

HodgePodge  displays  five  pull-down  menus  from  a  menu  bar  at 
ihe  top  of  Lhe  screen:  Apple  menu,  File  menu,  Edit  menu.  Windows 
menu,  and  1-onts  menu.  Wiihin  each  menu,  items  that  the  user  may 
select  appear  in  black;  items  Hiat  the  user  may  not  select  are 
dimmed  (gray).  When  the  user  selects  an  item  on  a  menu,  thai 
menu's  title  is  highlighted  until  the  selected  task  is  completed. 


New  desk  accessories  ore 
described  under  "Suppoitlng 
OJtief  Desktop  Features'  in 
Chapter  5. 


Apple  menu 

The  Apple  menu  is  a  standard  menu  that  all  desktop  applicaUons 
should  have.  Its  title  is  a  small,  colored  Apple  icon.  The  first  item 
in  the  Apple  menu  is  "About  HodgePodge."  SelecUng  it  brings  up 
a  dialog  box  that  explairts  a  bit  about  the  progam  and  its  authors. 
"About"  dialog  boxes  are  typical  of  desktop  programs. 

The  Apple  menu  also  lists  the  new  desk  accessories  available  on 
the  user's  system. 


What  HodgePodge  does 
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The  ClipboQj-d  and  the  concspts 
of  cut,  copy,  and  paste  ore 
described  under  "Suppoitrno 
Other  Desktop  Features"  In 
ChQptef  5. 


I 


File  menu 

should  have.  Here  it  contains  seven  items: 

■  Open:  Opens  a  picture  file  and  displays  it  in  a  window. 

■  Close:  Closes  the  frontmost  or  active  window. 

■  Save  Aii:  Allows  the  user  to  save  a  picture  window  with  its 
present  filename  or  under  another  name. 

•  Choose  Printers  Allows  the  user  to  select  a  primer. 

■  Page  Serup;  Lets  the  user  set  certain  parameters  for  printing. 

•  Print:  Prints  th:e  contents  of  ei±er  a  picture  window  or  a  fo 
window. 

■  Quit:  Shuts  down  the  program. 

All  of  the  items  in  the  File  menu  are  standard,  but  their 
implementation  in  some  cases  is  specific  to  HodgePodge. 


1 


I 


Edif  menu 

Jhould'Lv!"^"  ' ''"^''^  ^^'^^'^P  application^ 

Should  have.  Here  Jt  contains  five  items: 

■  Undo:  Allows  the  user  to  reverse  the  last  action  undertaken. 

■  Cut;  Deletes  tlie  selected  part  of  a  document  and  places  the 
selection  m  the  Clipboard, 

'  Cl^boarr  '  '''''^  "^^^"'^"^  P'^'     "  ^^'^"'"^"t ^« 

■  Paste:  Copies  the  conlenw  of  the  Clipboard  into  a  document 

"  S  cnp  w  '         ''''    ^  -"'^-^  ^^^-^''^ 

Hodgepodge  itself  does  not  use  the  Edit  menu;  however  the  Edit 
menu  must  be  present  in  ca.e  a  desk  accessor^  that  nee^^:is^' 


I 


Windows  menu 

The  Windows  menu  is  nothing  but  a  list  of  HodgePodge's 
currently  open  windows,  The  list  is  arranged  in  L  ord.r  in  which 

1  '^'^^^''^^      --'^  «f  -  Window  from 

Windows  menu  causes  that  window  to  be  brought  in  front  S 
any  other  open  windows  on  the  desktop  " 
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Fonts  menu 

With  ihe  Fonts  menu,  the  user  can  display  a  piece  of  sample  text 
using  any  font  on  the  system,  in  any  size  and  wilh  any  desired 
styling  variation  (such  as  bold  or  italic).  Selecting  the  first  item  on 
the  menu  brings  up  a  dialog  box  with  which  the  user  selects  the 
font  to  display,  and  then  draws  the  text  in  a  window.  Selecting  the 
second  item  toggles  the  display  of  the  next-opened  font  window 
between  proportionally  spaced  and  monospaced  display. 


Hodgepodge's  picture  windows 

HodgePodge  retrieves,  displays,  and  stores  color  pixel  images  in  a 
particular  type  of  picture  file.  The  user  may  open  a  file,  view  the 
picture,  and  then  save  the  file  again  with  the  same  or  another 
name. 

With  picture  windows,  HodgePodge  demonstrates  how  to  aeate 
windows  and  how  to  display  images  on  the  screen.  It  also  shows 
an  example  of  file  access  and  demonstrates  color  printing.  Figure 
2-2  is  an  example  of  a  picture  displayed  in  a  window. 


Figure  2-2 

A  Hodgepodge  picture  window 
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Hodgepodge's  font  windows 


HodgePodge  displays  sample  lext  in  windows  on  the  screen, 
text  may  be  in  any  point  size  and  may  have  any  combination 
styling  variations  such  as  bold,  italic,  or  underline.  The  text  ~ 
be  in  any  font  available  on  the  user's  system.  The  actual  lines 
text  that  are  displayed  are  specified  in  HodgePodge;  the  usei 
cannot  alter  them. 

Many  different  font  windows,  with  different  sizes  and  styles, 
be  open  simukancously.  Unlike  picture  windows,  font  windows 
not  opened  or  saved  as  files. 

With  font  windows,  HodgePodge  demonstrates  how  to  create 
windows  and  how  to  draw  text  on  the  screen.  Figure  2-3  is  an 
example  of  a  font  window  display. 


StiastonB 


Shaston  i 


The  quick  broun  fa^  jumps  over  the  Igisy  dot. 
Sh«  sells  %ia  shell;  iam  by  the  seer  jiiore. 
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Figure  2-3 

A  HodgePodge  font  window 


How  to  use  the  sample  program 

The  sample  program  serves  two  purposes.  First,  it  provides  a  re 
framework  williin  which  to  describe  how  Apple  IIGS  applications 
operate  and  how  ihey  should  be  written,  Second,  it  provides  you 
with  source  code  modules  that  you  can  adapt  to  your  own 
purposes  on  your  own  programs.  You  are  encouraged  to  use 
modify  any  applicable  parts  of  HodgePodge  for  any  programs 
you  write. 
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Because  you  may  be  writing  programs  in  any  of  various  available 
Apple  lies  languages,  we  provide  the  sample  program  in  three 
languagc^assembly  language,  C.  and  Pascal.  Complete  source 
code  listings  are  in  Appendixes  E  through  G.  The  parts  of  the 
program  listings  reproduced  in  Chapters  2  through  6  are  in 
Pascal, 

❖  Hodgepodge  versions:  Source  code  and  executable  forms  of 
Hodgepodge,  in  all  three  languages,  arc  on  the  disk  that 
accompanies  ihis  book.  Sightly  different  versions  of 
Hodgepodge,  with  differeni  features,  have  been  distributed 
through  other  sources  such  as  APDA.  See  Chapter  9. 


See  AppGndiit  D  for  a  complete 
listing  of  Hodge  Podge 
subroutines. 


Organization 


The  source  code  for  HodgePodgc  consists  of  many  individual 
subroutines  in  several  separate  files.  Figure  2-4  shows  the  overall 
organization  of  the  principal  routines.  The  main  program  (on  the 
left)  calls  each  of  the  principal  subroutines  (on  the  nght)  m 
order,  from  top  to  bottom. 


_  5etUpDefault 


Main  prngtam 


Quit 


InitGlobals 


StarHJpToolt 


—  SeWpMwnui 


SetUpWIndows 


Main  S'/ent  loop 
MalnEvent 


ShUtDownToo4i 


Figure  2-4 

Hodge  Podge  organization  (simplified) 


How  to  use  th&  sample  prografn 


HodgePodQG's  main  event  loop 
Is  described  undGr  'Cycte 
Through  the  Main  Event  Loop,' 
later  In  this  chopt&r, 


Pascal  Hodgepodge  was  written 
In  TML  Pascal™  for  APW.  S&e  the 
Blbliogtaphv. 


The  most  general  roudnes,  versions  of  which  will  probably  appa 
in  every  desktop  program  you  write,  a^e  more  heavily  shaded: 
Hodgepodge,  StartUpToola,  SetUpMenus,  MainEvent,  and 
shutD  own  Tools.  Most  execution  time  is  spent  in  the  main  even 
loop  (MainEvent)  and  in  the  subroutines  that  it  calls. 

Smaller  versions  of  Figure  2-4,  highlighted  to  show  particular 
subroutines,  accompany  discussions  of  the  principal  parts  of  the 
program.  Another  set  of  subroutine  diagrams,  starting  with 
Figure  2-5,  shows  the  flow  of  execution  within  and  from  the  main 
event  loop. 


Code-listing  convention 

The  HodgePodge  source  code  listings  in  this  chapter  and 
Chapters  3  through  6  are  in  Pascal.  In  addition  to  the  standard 
Pascal  syntax  and  notation,  please  note  the  following  conventioM! 

O  Toolbox  calls  are  in  boldface. 

□  Reserved  words  (such  as  if  then,  begin,  end,  goto)  are  in  italics 

□  Names  of  functions,  procedures,  types,  and  user-defined 
constants  begin  with  capital  letters, 

D  Names  of  variables,  fields  within  records,  and  toolbox-dermed 
constants  begin  with  lowercase  letters, 

o  Boolean  values  (such  as  TRUE  and  FALSE)  are  all  capital 
letters. 


HodgePodge 


HodgePodge  at  a  glance: 
the  main  program 

Brielly,  HodgePodge  (and  any  event-driven  application)  follows 
this  sequence  of  operations  when  it  execuiesi 

1.  It  starts  up; 

□  It  initializes  variables  and  data  structures. 

□  It  starts  up  the  tool  sets. 

□  It  sets  up  the  program's  menu  bar. 
2  I  t  continually  cycles  through  the  main  event  loop. 
3,  As  necessary,  it  handles  ap pi i cation-specific  events. 
4  Finally,  it  shuts  down. 
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rniB  HodgePodge  main  progrom 
Itin  ttl©  sOLrrce  file  HP.PAS, 


Mosl  of  the  above  tasks  are  carried  out  in  subroutines,  but  they  arc 
controlled  by  the  main  program.  It  is  very  short;  this  is  what  the 
Pascal  version  looks  like: 


program  HodgePodge; 

M 

1. 

i-l 

begin 

loitGlobals; 

if  StartUpToola  then 
begin 
SetUpDe fault; 
SetUpManua; 
SetCJpWindDwa 
MainEvent; 
esnd/ 


ShtrtDownTools; 


uid. 


(begin  HodgePodge..} 

tJSES    and  other  declaration 9) 

{Initialize  our  globals,  menus,  etc) 

iif  all  tool  aetg  loaded  OK...) 

I  Set  up  print  record) 
(Set  Up  menus} 
(Set  up  windows  1 
{Use  the  application} 

{Shut  down  IIGS  tool  seta} 
(End  of  Hodgepodge} 

Subsequent  sections  lead  you  through  the  principal  subroutines 
called  from  the  main  program.  The  subroutines  cover  the  steps 
common  to  most  applications^ — setting  up,  handling  events,  and 
shutting  down, 

The  details  of  how  HodgePodge  performs  its  own  specific  tasks, 
such  as  displaying  fonts  or  pictureSj  are  mostly  left  for  later 
chapters.  Here  we  are  more  interested  in  how  HodgePodge 
illustrates  the  general  independence  of  form  from  function  in 
event-driven  programs.  That  is,  from  a  general  point  of  view  most 
desktop  applications  look  pretty  much  the  same. 


Step  0.  Set  the  stage 

The  source  code  for  a  lypical  desktop  application  begins  with 
staiernents  that  bring  in  needed  library  files,  sets  up  the  operating 
environment,  and  perhaps  defines  some  data  slnjctures.  Many  of 
these  statements  control  what  happens  when  the  program  is 
assembled  or  compiled,  rather  than  when  it  executes. 
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□  For  assembly-language  programs,  ihb  category  ifirlvides  such 
casks  as  ,si:le::Ling  long  or  short  icgislcns,  loading  macro 
libraries,  and  initializing  various  toolbox  data  sti-ucEurtiH  wiiVi 


D  For  hig[i:;r-lpvel  programmiri;;  languagiiM,  I  his  category  may 
include  defining  variable  lypc'i,  dimensioning,  .arrays,  and 
loading  library  Hies.  '  ^ 

Kefcr  LC)  Appendix^^  E  through  C  f(.>r  details.  | 

iMiny  constants  acid  ih['A  striictLires  are  prcdt:firi[:cl  in  ilie  interface 
libraries  tn  i.he  .Apple  liGS  Toolbox,  and  tluis  need  not  be  defined 
wilhin  an  application,  Ulicy  imilude  format  and  Held  nuiucs  (ix 
trxilVjox  records  and  templattis,  and  predefined  constarWw  fnr 
values  such  as  cverU,  tri.Kies  and  memory-block  attribtctes.  We'll 
discuss  ttnL.>if:^  and  other  data  sLuctu[t:«  as  we  encounter  them  in 
ModgePodge, ,  id 


Widr  tlio  preliminaries  Out  ol  thc  way,  let's  look  n  program 
execution.  To  start  a  de.sklup  program  off  on  tlic  I'igl:!  fool,  you  ne'a 
to  initialise  any  j}r[)gram -specific  variables  antl  da  la  structures  yotii 
are  ftoing  to  use,  start  up  ihe  tool  scLs,  snd  set  up  the  system  rnenir 
bai. 


Initialize  variabtes  and  data  slructures  i 

Where  and  fi.ow  you  iJt^ftne  your  data  and  dai^  sfructuie^  depend 
upon  your  program's  purpose,  the  language  you're  usin;^,  and  yon: 
pejsonal  pr[:ferencc, 

Pa^seal  liodgePodgc  hks  three  subroutines  called  early  in  pr^jj^ram 
eKeculion  to  setup  initial  values  of  important  components  of  tlic 
prosrarrr,  Fven  though  two  of  llnjsp  routines  are  actually  called 
i3/ff?rtoo!  startup  {as  Figirrc  2-4  shows),  all  three  -.in:  grouped  hej^ 
for  simplicity,  In  general,  your  prograrris  will  do  some 
inStialiiiatioi!  before  starting  tool^i,  and  some  afisr. 

T.Jnlike  several  of  the  Hod^jePodge  routines  rkisfribed  in  this 
chapter,  these  initialisation  routines  arc  appplication-specific; 
your  program  may  have  very  diffe.rent  ones. 


using  direcrivr:s. 


Step  1 .  Start  the  program 


i 
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I-  InllGlobals 


r-  SetUpOefatjIt 


Set  Up  Windows 


InltGlobals  Is  In  tti&  source  file 
SLOBALS-PAS. 


<&  Note:  The  iniciatizalion  rouUnes  InitGlobals  and 

SetUpWindows  do  nol  appear  in  ihe  assembly-language  and  C 
versions  of  HodgePodgc.  In  those  languages,  variables  can  be 
initialized  as  they  are  defined  in  the  source  file,  rather  than 
during  execution. 

InitGtobals 

mitGlobals  is  the  Tirst  routine  called  from  the  main  program. 
It  initializes  several  variables  and  text  strings  used  later  in  the 
program;  we  will  not  describe  them  individually  bere.  It  also 
defines  the  tex:  strings  that  consUiuie  HodgePodge's  menus.  (The 
unusual  formaiiing  of  the  menu  strings  is  explained  under 
"Making  and  Modifying  Menus"  in  Chapter  5.)  In  addition, 
mitGlobals  creates  a  large  colored  Apple  icon  that  is 
displayed  in  the  "About  HodgePodge"  dialog  box  (Figure  4-14). 


procedure  InltGLobals; 

begin 

with  plaWtTettp  do 
begin 

S«tB*ct (dtBouodsRect, 120,30,520,80)  ; 
dtViaible  :-TRDE; 
dtRefCon  :-0; 
dtlt^nList [0]    ; -pointer (0) ; 
dtIt«nLiat[ll  :=MIL; 
and; 


{begin  InitGlobals™} 

{ten^slata  for  "Please  wait..."  dialog} 

( — format  defined  by  Dialog  Manager! 

(set  its  size} 

(make  it  visible} 

(no  special  info  here} 

{we'll  insert  this  poijnteE  later} 

{this  terminates  the  item  list} 

{Now  define  the  text  of  HodgePodge's 
inenu  titles  and  iteirifl :  } 


ApplaMenuStr  concat  ( '»@\N300X\0 ' , 

•  =jyoout  Hodge  Podgs- - .  \N3D1\0\ 
'==-\N302D\O. ')  ; 

FileKenuStr  concat('»    File  \N400\0', 

'—Open.  .  .\N401*Oo\0' , 
■  "=C1o3b\H2 5 5D V 0  \ 
'—Save  Aa.  .  AN403D\0'  , 

•  „-\KI4O4D\0'  , 

'■=Choose  Printer. . .\N405\0' , 
'—Page  Setup.  .  AN'JOeDXO' , 
'-=Print . . . \H40T*PpD\0 ' , 
'■— \N40eD\0'  , 
' — Quit\N409*Qg\0 . ' )  ; 


step  1 .  Stort  the  program 


EdltKenuStE 


WlndowMenuStr 


FontMenuStr 


Concat('>>  Slciit  \8J500D\0', 
•==tJndo\N250*Zz\(}'  , 
■ -=-\K501D\0 ' , 

' ==Copy \N2 32 *Cc\0' , 
'-■ 'Paste\M253*Vv\0 ' , 
'"='ClearVN25  4\{!.  ')  ; 

concac('>>    Window  \H$OOD\0', 

'==  Ha  Windows  AiiocatedXHeoiDXO. ' ) ; 

concat('»     Fonts  \N700\0', 

■==Display  Font. . .XNlOl^FfXO' , 

'--Display  Font  as  Mono-spaced\l]702*Mm\D, ' ) ; 


lastWindow  ;=  NIL; 

ncWindStr  := 

' -=No  Windows  Allocate<S\NG0lD\[3. 
raor.oStr  ;  ■= 

'""Display  Font  as  Mono-spaced'; 
proStr  := 

'-=Display  Font  as  Proportional"; 

isHonoFtsnt    :=  FALSE; 

vith  desiredFont  d'o 

f  amNum  SFFFE; 
fontStyle  0; 
fontSize  8,- 
snef,- 
wlndex  ; «-  0; 


SotEact (Applelcon.boundsRectfO,  0,  64,34) 
HPStijffHeK(@AppleIcon.dfl.ta[l] , 

' OOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOD ' ) 
MPStuf  fHex {(iAppleleon .data [2]  , 

'  OFFt'ETFFFFFrFFKFrFFFFFFFrPFFFFFO  •  i 

{.} 

I- 

{. 

(.) 


{Bow  initialize  other  variables, 
records  i  strings:) 

{window  Dointer] 


f  item  for  Windows  menu  J 
(Item  for  Fonts  menu) 
(IteTri  for  Fonts  menu) 
(start  fonts  as  proportional) 


{set  default  font  characteristics: J 

{ f ami  ly  niMiber  ] 
(plain  text) 
(8  pt.l 

(HIndax  is  the  number  of  open  windows} 

(Last,  define  the  colored  Apple  icon 
to  appear  in  the  "About..,"  box:) 

{size  of  icon) 

(HPStuffHex  puts  pixel  values  in  array} 


define  each  pixel  of  the) 
icon(aee  Appendix  G) } 
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HPStuff Hex Ofipplelcon, data [33) , 

■ OFFFFFFFFFFFFFFFrFFFFFFFFFFrFFFO ' ) f 

HPStUffHexteAppielCDn. data [341, 

■OOOOOOODOOOOOOOOOOOOOOOOOOOOOOOO- ) t 


(End  of  InltGlobala} 


SetUpDefault  In  the  soufce  ffle 
PRINT. PAS, 


piocedurs  SetUpDef ault  ,- 


SoTUpDetoult 

SetUpDef  ault  creates  a  default  print  record.  CPrKecHdl  is  a 
handle-type,  thai  references  a  Prim  Manager  print  record.) 
SetUpDef  ault  must  be  called  after  tool  startup  because  it  makes 
Memory  Manager  and  Print  Manager  cills. 


printHndl  ;-  PrRecHdl (Newanndl* (140, 

ntyMemcrylD, 

^  attrNoCroaa+attrLocted, 


PrD«fault (ptintHndl) ; 


sad; 


{begin  5et;tlpDefault...} 


{allocate  memory  for  print  record) 

{with  our  ID} 

{and  these  attributes  J 

(no  location  restriction  1 

{fill  record  with  default  values) 

(end  of  SetUpDef ault} 


SeWpWlndows  Is  in  tbe  source  fii© 
WINDOW.  PAS, 


SetUpWindows 

SetUpWindows  sets  initial  window  size  and  position  on  the 
screen.  It  is  called  after  tool  startup,  although  in  this  particular 
case  it  could  just  as  easily  have  been  part  of  InitGlobals. 


procedure  SetDpWindOWS  ; 

wXoffset  !-  20; 
wYoffaet  12; 

S*tB»CttiSi2Poa,10,20,330,B0) ; 


{begin  SetUpWindows...} 

(set  initial  window  poaitionl 
(from  top  left  corner  of  screen) 
(the  window's  port  rectangle) 
(End  of  SetUpWindowa ) 


Step  1.  start  the  pfogram 


-  StartUplQols  j 


StoftUpTools  Is  In  the  jource  file 
HP. PAS. 


Start  up  the  tool  sets 

Proper  iniiializatJon,  especially  for  the  Apple  IIGS  Toolbox,  l$ 
critical  for  successfully  running  an  application.  For  thai  reaso 
you  are  urged  to  simply  adopt  the  following  code  for  your  o 
programs.  It  works. 

In  HodgcPodge,  tool  startup  is  in  the  subroutine  StartUpToo 
called  from  the  main  program  right  after  InitGlobals.  T!ie 
steps  are  shown  here  in  the  order  in  which  they  are  executed ' 
Hodgepodge.  Although  that  is  not  always  the  precise  order  in 
which  ihcy  must  appear  in  your  own  source  code,  tool  startup 
order  is  in  general  very  important,  If  you  change  the  order 
without  knowing  exactly  what  you  are  doing,  your  program  tnay 
crash. 

The  tool  startup  subroutine  peforms  three  essential  tasks; 

1.  It  loads  the  absolutely  necessary  tool  sets — the  Tool  Locator, 
the  Memory  Manager,  the  Miscellaneous  Tool  Set,  QuickDra 
II,  and  the  Event  Manager 

2.  Using  a  tool  table  and  a  single  LoadTools  call,  it  loads  all 
other  tools  Hodge  Podge  will  need. 

3  It  starts  up  those  just-loaded  tools,  in  proper  order, 

*  Note;  Many  of  the  startup  calls  shown  below  require  inputs  or 
return  results.  Look  at  the  discussions  of  individual  tool  sets  i 
Chapters  3  through  5  for  more  information;  see  the  Apple  B 
Toolbox  Reference  for  complete  explanations. 

StartUpTools  begins  by  starling  up  the  five  basic  tool  sets.  It 
also  reserves  some  memory  space  (direct-page  space)  needed 
several  of  the  tool  sets. 


function  StarttJpTooia  :  Boolean; 


const     TotalDP  -  $B00 

DPForQuickDEaw  -  SOOO 

DPForEventMjir  =■  $300 

DPFoiCtlMgr  $400 

DPForLineEdit  -  $S00 

DPForMenuMgr  =  $600 

DPForStdFile  -  $700 

DPFocFontMgr  =  $8Q'0 

DPForPrintMgr  -  $900 


var       toolRec        ;  ToolTable; 
pariSinBlock  ;  FilaRec; 


fbegin  StartUpTools...) 


(11  pages  total  direct-page  space} 

(offset  to  QuickDraw  ndireet  pages} 

(offset  to  Event  Mgr  direct  page} 

(offset  to  Control  Mgr  direct  page} 

{offset  to  LineEdit  direct  page) 

[offset  to  Menu  l«^r  direct  page! 

{offset  to  Std.  File  direct  page} 

(offset  to  Font  Mgr  direct  pa^a) 

(offset  to  Print  Mgr  direct  pages! 

{Tool  Locator  record-type) 
(ProDOS  16  paranteter  block) 
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baseDF 


Integer 


(start  address  of  direct  pages) 


1; 

n 

Sta  rtUptool a : -TRUE ; 
QiecJcToolError  [$1}  ; 
itiyMeniorylD  :  =  H^iStartUp; 

KTStartDip; 

QieckTCKJlError  ($2)  ; 

taalaZeroPage 

»awHandl« (TotslDP , 
rayMeiTiDrylD, 
att  r  Bank+ att  r  Fi  K^d.+ 
att  eLo  cked+a  tt  tPage , 
PtriOn  .- 

ca\eclcTooiError  ($3) ; 
bftseDP  :=  LoHoudttoolsZeroPaga'^j ; 

(Ba  S  e  DP+  DPFor QuickDraw , 
Screen Mode , 

myMemorylD) ; 
ChackTaolErrof  (I  )  ,* 

EUStartap 

(BaseDP+DPForEvontMg r , 
20, 

0, 

0, 

200, 

UTyMemorylD)  ; 
CheckToolError  ( S5)  ; 


{label  used  for  dia)e-inount  loop} 


{Start  by  assuming  all  will  go  well} 
(start  up  Tool  Locator} 
{check  for  error) 

(Start-  up  Menvory  Manager:  it  returns 
a  Oiser  ID  for  HodgePodge  to  use} 
(Start  up  Misc  Tools) 
(check  for  error) 

(The  tools  need  direct-page  space:} 
(allocate  11  pages,  supplying...) 
(.JlodgePodge' 5  User  ID-.-) 

{„,the5e  meir»rY-block  attributes...} 
{„^d  make  it  in  bank  $0  0} 
(check  for  error] 

(gait,  the  2--byte  address  of  the  space} 

(address  of  QuickDraw's  3  dir.  pages) 
(€40  node} 

(max  size  of  scan  line} 
{Hodgepodge's  Usar  ID) 
{check  for  error) 

(address  of  Event  Mgr's  direct  page} 

(event  queue  size) 

(X  min  clatrtp} 

(X  max  clamp) 

(Y  min  clainp) 

(Y  imx  clanp} 

(Hodgepodge's  User  ID) 

(check  for  error) 


Next,  StartUpTools  loads  all  RAM-based  tools  and  RAAI 
patches  to  liOM-based  tools  at  once,  with  the  LoadTools  call.  It 
first  puts  a  simple  message  on  ihe  screen  10  notify  the  user  that  i: 
is  busy;  then  it  constructs  the  tool  table  [the  list  of  aJl  tools  to 
load);  and  then  it  loads  them. 


MoveTo(20, 20) ; 
SstBackColor  (  0  )  ; 
SatJer«Color (15) ; 


(Move  Pen  where  we  want  it) 
(Background  color  ^  black} 
(Foreground  color  =  wliite} 


Step  1 .  Start  the  program 
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Drawstring ( 'One  Moment  Pleass, , . ' 
ShowCursor," 


(Write  thfe  atjcing  on  screen..) 
(.^d  display  the  arrow  cursor} 


toolRec . 
toolRet. 
toolRec. 
toolRec , 
toolRec . 
toolRec . 
toalKec , 
toolRec . 
toolRec . 
toolRec . 
toolRec . 
toolRec . 
toolH#c , 
toolRee . 
toolRec , 
toolRec . 
toolEiec . 
toolRee. 
toolRec. 
toolRec. 
toolRec . 
toolRec . 
tool Esc . 
toolRec . 
toolRec . 
toolRec . 
tOolRei=. 
toolRec . 
toolRec. 


numTools 
tools [1 ] . 
tools [1] . 
tools [2] . 
tools [2] . 
tools [3] , 
tools [3] 
tools [4] 
tools  [4] 
tools [5 j . 
tools [5) 
tools [G I 
tools [6) 
tools [7  I 
tools [7  I 
tools [6] 
tools [8]  . 
tools [9] . 
toola [9J . 
tools [101 
toola [10) 
toola [111 
tools [11] 
tools [12] 
tools [12J 
tools [13] 
tools [13] 
tools [14J 
tools [14] 


!=  14; 
tsNuffl  :  =  "3 ; 
minVersion  0 
tsKum  S; 
minVersion  : ~  0 
tsNum  !=  6; 
minVeraion  :=  D 
tsNum  : =  14; 
minVeraion  D 
tsNum  15,- 
jTiinVeraion  :«  0 
tsNum  :=  16; 
ntifiVeraion  :•■  0 
taNum  :=  18; 
minVersion  :=  0 
tsNum  1=  19; 
minVersion  :=  0 
tsNum  2D; 
minVersion  :=  0 
•tsNum  21 
•minVersion 
.tsNum  22 
-minVersion 
.tsNum  :-  23 
.minVersion  0 
.tsSum  27 
.  minVersion 
.tsNum  28 
.minVeraion 


paramBlock. pathname  ;=  @ ' */sySTEM/TOOLS ' 
GET_FILE_INFO (paranSLocky ; 
if  toolErroO  thsn 

if  MountEootDiak  =  1  then 
goto  1; 

begin 

StartUpToola  FALSE; 
Exit; 

LoadToola (toolRec) ; 
CheckToolError($6)  ; 


{Now  load  RAM  baaed  tools 
(and  RAM  patches  to  ROM  tools) 
— first,  (Jefine  the  contenta 
of  the  Tool  table : } 

(14  tool  sets  to  be  loaded) 
(Quic]d3raw  //} 

(Desk  Manager) 

[E^srent  Manager) 

{Window  Manager) 

{Menu  Manager) 

{Control  Manager) 

{QuickDraw  Aux} 

{Print  Manager} 

{Line  Edit} 

(Dialog  Manager} 

[Scrap  Manager) 

{Standard  File) 

{Font  Manager) 

{List  Manager} 

(Now  load  the  tools  we've  defined:} 
(here's  the  label} 
f«=pathnama  of  tool  directory) 
[Look  for  that  directory:) 
{If  it's  not  there.,.} 
(Ask  user  to  mount  boot  disk...) 
{...If  OK  go  back  and  try  again) 
{But  if  user  cancels...) 

(tool  startup  fails ! ) 
{„,ao  quit  this  subroutine) 

{But  if  all  is  OK...} 

{...load  the  tools  named  in  Tool  Table 
(check  for  error} 
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Note  that,  if  the  disk  with  the  needed  tools  isn't  on  line, 
StartupTools  calls  the  routine  MountBootDiskj  which 
prompts  the  user  to  re  mount  the  boot  disk  so  tool  loading  can 
continue.  Mo  unt  Bo  otDisk  is  desaibed  under  "Error  Handling" 
in  Appendix  D. 

Once  all  the  tool  sets  have  been  loaded,  they  need  to  be  started 
up.  StartupTools  now  Starts  each  one,  in  the  proper  order  and 
with  the  proper  input  parameters  as  needed. 


WJjidStmrtUp  (iny  Memory  ID)  ? 
CheckToolError ( $7  J ; 

Raf  raahEaalctop  (NIL)  ; 

CtlStartDp 

[nsyMemorylD, 
Ba  seDP4DProECt IMg  c ) ; 
CheckToolError ($8) ; 

( Ba seDP+DPForLineEdit , 
n^eraorylD)  ; 
CheckToolErroir  ($9) ; 

Dlk logs tart Up 

(nti'MenioEylO)  ; 
CheckToolError ( SA)  ; 

HanuStart^ 

[ir^MaitiorylD, 
BaseDP+DPForMenuMgr)  ; 
CheckToolError (5B) ; 

D«»kStartUp; 

CheckToolError (IC) ; 

ShowP  1  ea  3  eWait  ,- 


Srst&rtDp 

(uYMemorylD, 
BaseDP+DPForStdFile) ; 
CheckToolError  [$D} ; 
SFAllCapa (TRUE) ; 

{^DAuxStartOp; 

CheckToolError  {$E| ; 


( start  up  Window  Handler} 
(check  for  error! 

(redraw  desktop} 

(start  up  Control  Manager) 
(Dser  ID  for  meraoEy  bloeka) 
{address  of  Ctl  Mgr'a  direct  page  J 
{cheek  for  error) 

(start  up  Line  Edit} 
(addreaa  of  LineEdit's  direct  page) 
(User  ID  for  memory  blocks} 
(check  for  error J 

( start  up  Dialog  Manager) 
(User  ID  for  memory  hlockg) 
( check  for  error) 

{start  up  Menu  Manager) 
{tJserlD  for  memory  blocks) 
{addzrfiaa.  of  Menu  Mgr'a  direct  page) 
{check  for  error) 

{start,  up  Desk  Manager) 
{check  for  error} 

{Bring  up  a  dialog  box  that  says 
"Please  wait  while  we..."  } 

(start  up  Standard  File} 

((JserlD  for  memory  blocks) 

{address  of  Etd  File's  direct  page) 

(check  for  error) 

{Display  file  namea  in  all  caps) 

(start  up  QuickDraw  Aux} 
(check  for  error) 


Step  1 ,  Start  the  program 
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Waitcursor; 
rust art  Up 

{inyMeiTcrylD, 

BaseDE+DPForFontMgr)  ; 
CheekToolError ($F} ; 
XiatStartqp; 
Chee]cToolErzor  ($10)  ; 

ScrapStartUp; 

CheekToolError (SI 1) ; 

PMStartUp 

(n^MeirorylD, 

EaseDP+DPForPrintMgr)  ; 
CheekToolError  (Sl2]i  ; 

HidePleaseWait; 
InitCuraor/ 

end; 


(put  up  watch  cursor, 
now  that  it ' a  available) 
(start  Up  Font  Manager) 
(EJsarlD  for  meniory  blocks) 
(address  of  Font  Mgr'a  direct  page) 
(check  for  error) 

(start  up  List  ttonager) 
(check  for  error) 

(start  up  Scrap  Manager) 
(check  for  error) 

(start  up  Print  Manager) 
{User ID  for  memory  blocks) 
(address  of  Print  Mgr's  2  dir.  pages) 
(check  for  error) 

(Remove  the  "Please  wait...") 
(restore  nonnal  cursor) 

(End  of  StartOpTools) 


ShowPieaseWoit  and 
HIdePleaieWalt  ore  dsscrib&d 
under  "Construcling  Dialog  Boxgs 
□nd  Alerts'  In  Chnpfar  A. 


This  completes  toolbox  initialization.  The  routine  StartUpTools 
ends  and  returns  control  to  the  main  program  which,  in  addition 
lo  calling  the  two  short  initiali^^ation  subroutines  Setup  Windows 
and  SetUpDe fault  (described  earlier  in  this  section)  calls  the 
subroutine  that  sets  up  the  menu  bar.  That  routine,  SetupMenug 
IS  described  next.  ' 

«-  SbowPieaseWait:  During  tool  startup,  the  HodgePodgc  routine 
ShowPleaseWait  is  called,  It  puts  up  a  dialog  box  that  inlbnns 
the  user  that  the  startup  process  may  take  a  few  seconds  When 
startup  1.S  done,  HidePleasewait  removes  the  dialog  box  from 
the  screen.  Keeping  the  user  informed  is  an  imponant 
component  of  the  Human  Interface  Guidelines.  U 

❖  Emir  handling:  You  may  have  noted  that,  after  each  tool 
startup  call,  the  ModgcPodgc  subroutine  CheekToolError  is 
called,  CheekToolError  is  a  very  simple  error  handling 
routine;  it  is  described  under  "Error  Handling"  in  Appendix  D. 
U  IS  good  pracuce  to  rouUnely  check  for  errors  after  making 
tool  calls  that  can  return  thera. 
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SelUpMuriuS 


SatupMpriNS  h  In  'lis  scijrcfj  file 


Set  up  the  system  menu  bar 

Tlic  lOuLiLie  that  sets  up  the  menu  har  when  Dod^^i'odgt:  .siiiri^  up 
is  called  Sel:  vipMenu.'s.  fJetupMeimJ  is  called  frorn  [he  main 
prograrti,  after  StartUpToois  and  iho  Lwo  iim-Al  JxiiliaUzalion 
routiaea. 

For  each  menu  in  lyrn,  SetupKeriu.«3  calls  the  Menu  Manager 
routine  NewMenu,  passing  it  a  pointer  to  a  sel  yf  di:irm:[er  sti'icigs 
lhal.  tk'Xim:  iht:  menu  name  and  the  items  it  contains.  ('I'he  menu 
strings  were  deHnmlin  Uie  routine  Inil-Giobiils  J  New.Menu 
returns  a  handle  to  the  newly  rri'ial.iid  menu.  Se^LupMer.  uo  then 
calls  hisertMenu,  passing  it  the  menu  handle  and  ;i  jinsilic^n 
parampk^r  (Ijerc  defaulted  to  zero),  10  put  itic  menu  jnto  I  he  menu 
bar. 

FinaUy,  :;et:UpM6iiuLj  adds  aSl  desk  accessory  names  io  {he.  .AppU: 
menu  Cwiih  ihe  Des1fMMrs^jg{:.r  call  FixApplemenuJ,  calculates  the 
height. of  the  menu  bar,  and  draws  the  bar. 


SfltMTltleStart (10}; 

InsartMenu  ^NewManu  ( @  i'oi  i  L  M^i  :i      L  f  [  1  ]  )  ,  0 )  ; 
InaajctMenu  (NewMena  ( tWiiiiJ.jwMyiiaSt  1  [1]  }  ,  C)  ^ 
InscrtM&nu  ^NowMonu  ((5Edit.Mf:^nuSt.?:  t1  1  )  ,  f!)  ; 
InsertMonu (NowMcmu (OFiieMonuStr  f 1 1 ) , 0) j 

FiKA-ppleMonu  ( A jivi  1- et-fe  nii  1 D )  ; 


height  :=  FixM&rtuBar; 
DrawMBnuBmr; 


encf; 


{begin  SatupMer.'jis.,.) 

{-  height  ot  (m^uu  £lhiL) 


tSet  ytiii-L  pij^iition,  from  Left.  5;rlqe 
of  menu  ban,  of  first  siiomi  r.itle} 
{create  inm^l  Hi-iBftrt.  Fnnta  l-fanu) 
{create  ana  HnKert  Windows  MsnuJ 
{cripate  and  insert  Jldit  l-lanL:) 
{^nteste  snd  inssrt  File  Men':;) 
{r:  rest  ft  and  inasEt  Apple  t-lsnuf 

{Adtd  DAs  to  appie  menu} 

{Get  sizes  of  merjugj 

{  .  . ,  dj;  aw  Lin;       lu  ;jar !  ) 

{Erid  of  £ettJ^;tit.inuy ) 


step  1 ,  Sidrt  frie  pro^^rdJTl  47 


step  2.  Cycle  through  the  main  event  loop 


I  


MainEvent 


ToskMaster  and  GetNextEvent 
ore  further  described  under 
'Hondling  Events'  in  Chapter  3. 


A  desktop  application  spends  most  of  its  time  in  the  main  event 
loop,  waiting  for  an  event  to  handle.  How  an  application  functions 
is  determined  hy  what  events  it  chooses  lo  handle  and  how  it 
handles  them.  The  event  loops  for  most  programs  are  quite 
similar — it  is  in  the  subroutines  to  which  the  various  events  cause 
branches  that  the  special  personality  of  each  application  lies. 

Hodgepodge's  main  event  loop  is  diagrammed  in  Figure  2-5. 
Each  time  through  the  loop,  HodgePodge  checks  whether  it's  time 
to  quit.  If  it  isn't,  HodgePodge  adjusts  menu  items  if  necessary  m 
and  then  looks  for  the  next  event.  It  does  this  by  calling  the  I 
Window  Manager  routine  TaskMiisteK  Alternatively,  an  I 
application  could  call  the  Event  manager  routine  GeiNextEvent. 

HodgePodge  uses  Task-Master  because  TaskMaster  automatically 
handles  many  events  for  it.  TaskM aster  itself  calls  GetNextEvent, 
and  takes  care  of  events  that  affect  the  size  and  shape  of  windows, 
such  as  a  mouse  click  in  the  Zoom,  Close,  or  Grow  boxes.  This  is 
not  a  requirement;  your  application  can  ignore  TaskMaster 
entirely  and  do  all  event-handling  itself  For  example,  you  might 
not  use  TaskiMaster  if  you  want  the  application  lo  respond  in  an 
atypical  manner. 

If  TaskJMaster  can't  completely  handle  an  event,  it  passes  a  task 
code  (described  in  "Handling  Events"  in  Chapter  3)  back  to  the 
application,  and  the  application  must  deal  with  the  event 
specified  by  that  code.  For  example,  if  the  user  selects  a  menu 
item,  TaskMaster  passes  the  information  back  to  the  application, 
which  must  find  out  which  item  was  selected  and  take  the 
appropriate  action. 

When  action  on  an  individual  event  is  tinished,  the  application 
Cor  TaskMaster)  returns  lo  the  main  event  loop  to  wait  for  the  next 
event. 
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Figure  2-S 

Hodgepodge's  main  ©vent  loop 


The  [OOP 

MolnEvent  Is  hiha  source  file  Here;  is  Ihe  code  for  Hodgepodge's  main  event  loop.  Compare  it 

EVENT. PAS.  with  Figure  2-5.  Depending  on  its  features,  your  application  may 

have  an  identical  event  loop,  or  i:  may  respond  to  a  different  set 

of  events. 


Step  2.  Cycle  through  the  mcAn  event  loop 
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procedure  MainEvent; 
var        code :  Integer; 

Event.wniTaakMask  :=  SOOOOIFFF; 
done  FALSE; 

repeat 

CheckFrontW; 

code  :=  Ta.sXMaat«r(SFFFF,  Event); 


esse  code  of 
wInGaAway : 
DoCloseltera; 

wlnMenuBar : 
DoMenu 

end; 


until  done-; 


(be^in  Main£vent..,} 

{thfi  task  code  (or  event  code) 
returned  by  TaslcMaster) 

(pass  all  events  to  TaakMaatar) 
(initialize  the  Quit  flag] 


(adjust  menu  items  if  necessary) 
{Call  TaskMaster:  let  it  handle 

all  events ;  recoird  ndme=Event;  it 

returns  the  task  code) 
( If  the  tagk  code  represents...} 
(If  a  window  close  box  selected...} 
(...go  to  DoCloseltem) 
(If  an  Edit-menu  item  or  a...} 
( -.regular  menu  item  selected..) 
(_.go  to  DoMenu) 
{end  of  Case  statement) 

(Stop  when  Done=rRUEl 
{End  of  MainEvent} 


The  diTferent  events  are  specified  by  toolbox-defined  constants 
(such  as  winMenuBar)  that  define  Event  Manager  and  TaskMasier 
event  codes.  See  Chapter  3. 

The  main  event  loop  here  is  much  shorter  than  it  would  be  if 
TaskJVlasicT  were  not  used.  Without  TaskMasier,  there  might  i 
been  as  many  as  l6  separate  items  in  the  above  case  siateme 
each  with  its  own  subroutine  call. 

*  Check  front  window:  Each  time  through  the  loop,  before 
checking  for  events,  HodgePodge  determines  which  window 
any)  is  the  frontmost,  and  adjusts  menu  items  accordingly, 
example,  if  the  front  window  is  a  font  window,  the  Save  item 
the  File  menu  should  be  disabled  because  HodgePodge  dc 
not  save  font-window  contents  to  disk.  If  the  front  window  is 
desk  accessory  window,  the  Edit  menu  should  be  enabled. 

The  routine  that  does  this  menu  manipulation  is  CheckFroii 
It  is  in  the  source  file  EVENT  .  PAS.  See  Appendbc  G, 
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step  3.  Handle  specific  events 

Ii  may  already  seem  ihal  the  organixation  of  ihis  program  is  a 
lilLle  different  from  what  you  expected.  So  far^  we've  seen  no 
major  divisions  of  the  code  into  "Picture  Window  Stuff  and 
"Font  Window  Stuff."  as  you  might  expect  in  a  program  whose 
principal  tasks  are  the  manipulation  of  picture  windows  and  font 
windows- 

Evem-driven  programs  have  the  equivalents  to  such  modules,  but 
they  are  chopped  up  and  arranged  in  different  ways.  Elcmenis  of 
them  are  distributed  throughout  the  flow  of  events  in  the  program 

'ITverefore  let's  continue  along  the  path  of  execution,  seeing  where 
we  go  when  we  leave  the  main  event  loop  lo  handle  the  events 
that  Hodgepodge  responds  to.  We'll  mention  each  of  the  types  of 
events  and  point  you  to  where  in  the  book  to  look  for  the  specific 
rouUne  that  handles  that  event  type. 


Window  closing  Is  described 
under  "Window-Related  Events/ 
later  in  this  seclton., 


Window-content  dednltlon 
procedures  aie  discussed 
under  "CfeotlnQ  Windows'  In 
Chapter  4, 


TaskMaster-handled  events 

In  Hodgepodge,  TaskJVlaster  automatically  handles  all  moving, 
resizing,  scrolling,  activating,  updating,  and  redrawing  of  windows. 
It  handles  nearly  all  window  events  automatically.  This  is  a  great 
convenience  (as  you  can  imagine  if  you  are  a  Macintosh 
programmer)  and  it  means  that,  apart  from  closing  a  window, 
there  is  little  for  HodgePodge  to  do  in  terms  of  window 
manipulation. 

In  general,  there  is  one  thing  that  TaskMaster  cannot  do  for  an 
application,  and  that  is  draw  the  contents  of  a  window.  TaskMaster 
cannot  know  what  purpose  the  application  created  the  window  for. 
But,  if  a  windovif's  contents  can  always  be  described  by  a  routine, 
an  application  can  provide  TaskMaster  with  a  way  to  call  that 
routine  whenever  a  window  is  drawn,  That  routine,  although  part 
of  your  program,  acts  as  a  sort  of  extension  to  TaskMaster,  and  it 
can  do  the  redrawing  of  the  window's  contents.  Such  routines  are 
called  window- con  lent  definUion  procedures. 

HodgePodge  uses  this  trick  for  both  picture  windows  and  font 
windows.  Figure  2-6  is  an  extension  to  part  of  the  event-loop 
diagram  of  Figure  2-5,  and  shows  the  window-drawing  routines  that 
are  called  from  within  TaskMaster. 
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Patnt 


TaskMaiter  |— 


no      Any  ' 
event  / 

■\   ?  /■■ 


Figure  2-6 

HodgePodgo  routines  called  by  ToskMaster 

^  Nole:  Don't  get  the  Impression  from  Figure  2-6  that  drawing  I 
window  contents  is  aU  that  TaskAlaster  does,  TaskMaster  i 
many  more  things,  as  already  discussed,  but  Paint  and 
Di spF on t Window  are  the  only  HodgePodge  routines  that 
TaskiMaster  calls, 


Palnf  Is  In  the  source  life 

PAINT. PAS. 


Picture  window  contents 

When  a  picture  window's  contents  need  to  be  drawn  or  redraw 
TaskMaster  calls  the  definition  procedure  Paint,  which  setsvpj 
the  proper  parameters  and  then  calls  the  routine  PaintTttoi 
the  actual  drawing.  Paint  It  is  described  under  "Drawing  to! 
Screen  (and  elsewhere)*  in  Chapter  3.  Paint  looks  like  this: 


procedure  Paint; 

var       trapPort.         :  GrafPortPtr; 
myDd  taHa  ndle :  Mi  ndOataM; 

tmpPort  :»  GsbPocb; 

it^DataHandle  WindDataHl 

GfttWRaf  Con  (tnipPort)  J  ,- 

Paint  It  (iTiyDataHandle-^^.pict)  ; 

end; 


{begin  Paint „.} 

(pointer  to  a.  gtafPort} 
(handle  to  a  window-data  record 
—defined  in  GL0BAL3.PASI 

(get  a  pointer  to  current  port} 
(Get  a  handle  to  the  window-data...) 
(...record  for  the  current  portj 
(Osing  the  picture  pointer  in  the...) 
(,., record,  call  the  routine  that 
draws  picture -window  contents} 
{end  of  Paint} 
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Nolc  that  Paint  (andPaintlt  too,  as  you  will  see)  is  completely 
unconcerned  about  where  on  the  screen  the  window  to  be  drawn 
appears,  what  oiher  windows  may  or  may  not  be  in  front  of  it,  and 
even  how  big  the  window  is  or  what  part  of  the  picture  is  being 
displayed.  All  these  details  are  taken  care  of  by  the  toolbox! 


Font  window  contents 

When  a  font  window's  contents  need  to  be  drawn  or  redrawn, 
DlipFohtWlndow  Is  In  tt^e  sourcs  TaskMaster  calls  the  definition  procedure  DispFontwindow, 
file  FONT.PAS.  which  sets  up  the  proper  parameters  and  then  calls  the  routine 

ShowFont  to  do  the  actual  drawing.  ShowFont  is  described  in 

Chapter  3,  under  "Drawing  to  the  Screen,"  DispFont Window 

looks  like  this: 


procedure  DlspFontWindow; 

var       tnjiPDtt  :  GrafPortPtr; 

rnyCataKandle:  WindDataB; 

begin 

tirpPort  :-  SatPort; 

iiyDataHajndle  WlndDat.aH( 

GatWRafCon (tmpPort) ) ; 

vith  myDataHandle""  db 
ShowFont (theFont, isMono) ; 

end; 


{begin  I]ispFontWtndoM„.) 

(pointer  no  a  Graf Port) 
{handle  to  a  window-data  record 
—defined  in  GLOEALS.PAS} 

{Get  pointer  to  current  port) 
(Get  a  handie  to  the  window-data...) 
{_j:ecord  for  the  current  port) 

{Using  font  info  from  the  recordU.} 
{...call  the  routine  that  draws 

font-window  contents } 
{End  of  DispFontWindowJ 


Just  as  in  the  case  of  picture  windows,  DispFontwindow  and 
ShowFont  are  conipletely  unconcerned  about  where  on  the 
screen  the  window  to  be  drawn  appears,  what  other  windows  may 
or  may  not  be  in  front  of  it,  and  even  how  big  the  window  is  or 
what  part  of  the  font  display  is  to  be  drawn,  'ITie  toolbox  does  it 
all. 
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Menu- related  events 


Each  of  the  subroutines  listed  in  this  section  is  called  as  the  r 
of  a  menu  selection  made  by  the  user.  Thus  there  is  one 
subheading  for  each  HodgePodge  menu  entry.  Figure  2-7  is  an 
extension  to  part  of  Figure  2-5;  it  shows  which  routines  can  he 
called  when  the  main  event  loop  sends  a  menu-related  event 
the  routine  DoMenu. 

When  a  menu  item  is  selected  (either  with  the  mouse  or  with 
keyboard-equivalent).  TaskMaster  returns  17  ( =°  wlnMenuBar 
see  "Handling  Events"  in  Chapter  3)  as  the  value  of  myEvent, 

DoMenu  is  In  the  source  file  which  causes  execution  to  pass  to  the  subroutine  DoMenu. 

MENU. PAS.  TaskMaster  also  sets  the  taskData  field  of  the  extended  task 

event  record  equal  to  the  menu  ID  and  the  ID  of  the  item 
selected,  and  then  passes  control  back  to  HodgePodge  so  it 
perform  the  specific  task.  DoMenu  looks  like  this: 


procedure  DoManu ; 


{begin  DoMenii..) 


vai  menuNum: 
IteETitfum: 


Integer; 
Integer; 


begin 

inenuNum  BlWord (Event .wmTagkData) . 
it.emHum        LoWozd (Event  .wmTaakData) . 


case  iteroNum  of 
About.  Item: 
Openltem: 
ClDseltein: 
SaveAsItem; 
ChoosePItemi 
PageSetltem; 
Printltein: 
Quitltem: 
Dndoltem: 
Cut I tern: 
Copyltem: 
Pasteltem: 
Clearltem: 
Font Item; 
Monoltem: 

DoWindow  (IteniNum) 


DcAbout  Item; 
DoOpenltem; 
DoCloseltera; 
ttoSaveltemv 
DoChooserltem; 
DoSetupItem; 
DoPrintltera; 
DoQuitltem; 


DoOpenltem; 
DoSetMono; 


Hllit«M«nu (FALSE, raenuNum) ; 


end/ 


(get  nuitiber  of  menu  and  item} 


(bring  up  "About  HodgePodge"  dialog) 

(open  a  picture  window} 

{close  a  window} 

(save  a  picture  file) 

(choose  a  printer) 

(do  page-setup} 

(print  contents  of  a  window} 

(quit.  HodgePodge} 


(ignore  special  menu  itema) 

(open  a  font  window) 
( set  font  spacing} 

{bring  the  cJioaen  window  to  front) 
{of  Case  statement} 

{unHicfhlight  rnenu  title) 

{End  of  DoMenu) 
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The  menu  ID  variables  (Closeltem,  About  Item,  and  so  forth) 
arc  defined  in  ihe  source  file  GLOBALS  .  PAS. 


DoWlndow 


DoCloseltem 


DoAboutltem 


DoQultltem 


DoOpenltem 


DoSoveltem 


DoChooseltem 


DoSetupltem 


DoPrlntltem 


DoSetMono 


Figure  2-7 

HodgePodge  routines  that  handle  menu-related  events 

The  various  routines  called  by  DoMenu  are  listed  either  elsewhere 
in  this  book  or  in  Appendix  G.  In  brief,  this  is  what  each  does: 

■  DoAboutltem;  Brings  up  the  "About  HodgePodge"  dialog  box. 
DoAboutltem  is  listed  under  "Constructing  Dialog  Boxes  and 
Alerts"  in  Chapter  4, 

■  DoOpenlteixi:  Opens  a  font  or  picture  window.  DoOpenltera 
calls  Openwindcjw  to  open  the  window,  then  calls  AddToMenu 
to  add  the  window's  name  to  the  Windows  menu.  DoOpenltem 
is  listed  under  "Opening  a  Window:  An  Example"  in  Chapter  4, 


Menu  X  V^^J 
event 

■.    •>  /  I. 


DoMenu 
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■  Doaoseltem:  Closes  a  font  or  picture  window,  releases  its 
allocated  memory,  and  adjusts  the  Windows  menu. 
DoCloseltem  is  listed  under  "Window-Related  Events  "  lat 
m  tills  section, 

■  DoSai^ertem:  Saves  the  contents  of  a  picture  window  as  a  diskl 
file.  Do  Save  It  em  is  listed  under  "Communicating  With  Files! 
and  Devices"  in  Chapter  S.  * 

■  DoChooserliem-  Brings  up  a  dialog  box  permitting  Lhe  user  i 
choose  a  prmting  device.  DoChooserltem  is  listed  under 

CommunicaUng  With  Files  and  Devices"  in  Chapter  5, 

■  DoSetupltem:  Brings  up  a  dialog  bojc  permitting  the  user  to ' 
page-setup  paramefere.  DoSetupItem  is  listed  under 
XommunicaUng  With  Files  and  Devices"  in  Chapter  5, 

■  DoPrlnmem;  Prints  the  contents  of  the  frontmost  window  j 
DoPrintltem  is  listed  under  -Communicating  Wiih  Files  aj 
Devices"  m  Chapter  5. 

■  DoQultltem;  .^igns  the  value  TRUE  to  the  boolean  variable 
done.  That  causes  leminaUon  of  the  main  event  loop 
DoQuitltem  is  in  the  source  file  MENU .  pas.  See  Appendix 

■  DoSetMono:  Toggles  a  Hag  that  controls  whether  fonts  are 
displayed  as  moncspaced  or  proportional,  and  updates  the 
honts  menu  accordingly.  DoSetMono  is  in  the  source  file 
FONT.  PAS.  See  Appendix  G, 

■  T'"***"^'  "^""^  "^"^  '^'^^'^^  ^'"^1°^  t^^Jio^en  from  the 
Wmdows  menu)  lo  the  front.  DoWindow  is  in  the  source  file 
MENU .  PAS,  Sec  Appendix  G. 


Window-related  events  ~  " 

Closing  is  the  only  window-related  event  that  HodgePodge  must 
respond  to  explidtiy.  Figure  2-8  .s  an  extension  to  part  oFpiguTe  | 
2-5;  Jt  shows  the  routines  that  can  be  called  when  the  main  evenill 
loop  encounters  a  window- related  event. 
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•-'  Close 

window  \  

■-.  event 


J 


no 


-+i  DoClo&eltem 


1__ 


AdJWind 


Figure  2-8 

Hodgepodge  routines  that  handle  window-relafod  events 


OoClosslfem  In  the  source  file 
WIN  DOW.  PAS. 


Closing  is  a  window  event,  bui  ii  is  also  a  menu  event  .  When  ihe 
user  clicks  in  an  acUve  window's  dose  box,  or  selects  Close  from 
the  File  menu,  TaskM aster  returns  that  information  to 
HodgePodge,  which  in  turn  calls  DoClaseltem,  DoCloaeltem  is 
also  called  at  program  shutdown,  to  close  all  windows.  Its  source 
code  looks  like  this: 


proeetfyre  DoCloseltem; 

var       theWindow      ;  GrafPortPtr; 
myDataHandle :  WindDataH; 

begin 

theWindow  ;~  FrontWlndow; 

CloiaHDAbyWinStr  (theWindow)  ; 
if  isTocslError  t-hen 

Ad j Wind (theWindow) ; 
nyDataHandle  :-  WindDataH ( 

G*tWRofCon (theWindow) ) 
DiopoaaHandls (Handle (myDataHandle) } ; 
ClovaWindow (theWindow) ; 
Dac  (windex) ; 
end/ 

9ndr 


(begin  DoCloaelteiru,} 

(ptr  to  Mindow  to  be  closed} 
{windDW-data-reosrd  haj-idle) 

(Get  a  pointer  to  the  front  window} 

{ Assume  that  it ' s  a  d&ak.  acc.  window) 
(If  it  wasn't  an  NDA  window..,) 

{Call  AdjWind  to  update  menu) 
[Get  a  handle  to  window's...) 
{...window-data  record} 
(Get  rid  of  the  window-data  record} 
(Get  rid  of  the  window  corrpletely} 
(decrease  nuiriber  of  open  windows) 
(end  of  If  wasn't  an  NDAl 
(end  of  DoClogaltam} 


❖  AdjWind:  DoCloselteni  calls  the  HodgcPodge  routine 
AdjWind,  which  removes  the  name  of  the  just-dosed  window 
from  the  Windows  menu.  AdjWind  is  descrilx:d  under  "Making 
and  Modifying  Menus"  in  Chapter  5. 


Step  3.  Handle  specific  ©vents 


57 


_  SfiutDownToali 


ShutDownTools  Is  In  the  sourca  file 
HP.PAS. 


Step  4.  Shut  down  the  program 

when  it's  time  for  your  application  to  quit,  the  following  steps 
ensure  a  graceful  exit: 

1.  Shut  down  all  tool  sets  in  reverse  order  from  the  way  you 

started  them  up. 
Z  Release  any  memory  your  application  requested  from  the 

Memory  Manager. 

3.  Shut  down  the  Memory  Manager  (with  your  application's  Iser 
ID  as  input). 

4.  Shut  down  the  Tool  Locator. 

5.  In  assembly  language,  use  the  FroDOS  i6  QUIT  call  to  leave  the 
application.  On  C  and  Pascal,  this  is  taken  care  of  for  you). 

HodgePodge  terminates  when  the  user  selects  Quit  from  the  File 
menu.  'Hie  routine  DoQuit  It  em  executes,  setting  the  variable  donj 
to  TRUE,  which  causes  llie  main  event  loop  to  stop.  Execution  pim 
to  the  main  program,  which  calls  ShutDownTools  and  ends. 

ShutDownTools  shuts  down  all  tool  sets,  in  reverse  order  ffomi 
startup.  You  may  be  able  to  use  this  code  verbatim  in  your 
programs,  It  looks  like  this: 


procedure  ShutDownTools; 
begin 

DaskShutOown; 

if  WifidStatuo  <>  0  then 
H  ideAl  IWindovj  s ; 


LI  •  t  Shut  D  own ; 
FMShutDown ; 
S crap Shut Down, - 
PMShutDown; 
QDAux Shut Down ; 
SFShutDown; 
UanuShutDown  ,■ 
DialogShutDown ; 
XEShutPown; 
CtlShutDown; 
WindShutDown; 
EMShutDown ; 
QD Shut Down , ■ 
MTS hut Down; 


(begin  ShutDownTools...] 


I  shut  down  Desk  Manager} 
(inake  sure  Window  Mgr.  setive„.} 
(close  all  windows — this  may  taXe 
some  time  if  many  open  windows!} 
{shut  down  List  Manager} 
(shut  down  Font  Manager} 
{shut  down  Scrap  Manager} 
I  shut  down  Print  Manager} 
{shut  down  Quick  Draw  Aux} 
I  shut  down  Standard  FileJ 
(shut  down  Menu  Manager} 
(shut  down  Dialog  Manager) 
{ shut  down  Line  Edit } 
{ahut  down  Control  Manager} 
( shut  down  Window  Manager} 
I shut  down  Event  Manager} 
{shut  down  Ouic)tDraw  II} 
(shut  down  Misc.  Tool  Set} 
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if  MMStatu*  <>  0  the/i 
begin 

Di»poa«BIandla (toolsZeroPage)  ; 
MMShutDovn  (myMemoiTYlD)  ; 
and," 
TLSKutDown; 

end; 


{If  Memory  Mgr.  active..} 
(delate  the  direct-page  memDry-.} 
(...allocated  at  startup) 
(shut  down  Memocy  Manager} 

(shut  down  Tool  Locator} 
{End  of  ShutDovmToola} 


*  HideAliWindows:  Note  that  shutDownTools  calls 

HideAllWindows,  which  simply  doses  all  windows  and 
releases  their  associated  memory.  HideAliWindows  is  in  the 
source  file  WINDOW.  PAS.  See  Appendix  G, 


Conclusion 

This  completes  our  overview  of  the  organization  of  HodgePodge. 
You  can  see  that  il  has  a  structure  almost  independent  of  the  tasks 
it  was  written  to  perform.  That,  of  course,  is  the  intention— if  all 
event-driven  progranis  execute  in  a  similar  manner,  they  can 
present  a  uniform  interface  to  the  user,  In  addition,  they  can  be 
extended  easily  to  add  new  features,  and  they  can  remain 
compatible  with  future  revisions  of  system  software. 

The  rest  of  the  book  gives  more  details  on  how  HodgePodge 
actually  performs  its  individual  tasks,  and  gives  some  of  the 
concepts  behind  the  tool  calls  that  HodgePodge,  like  any  event- 
driven  program,  needs  to  make.  Most  discussions  are  general,  but 
HodgePodge  listings  are  included  where  appropriate.  See  Table  2-1. 


Table  2-1 

HodgePodge  routines 


described  In  this  book 


l7outln« 


S«e  chaptar  and  s&ctlon... 


AddToMenu 

AdjWind 

AskUaer 

CheckToolError 

CheckDialtError 

Di  spFontWindow 

DoAboutltera 


Chap.  5:  "Making  and  Modifying  Menus" 

Chap.  5:  "Making  and  Modifying  Menus" 

Chap.  5:  "Communicating  With  Files,.." 

App,  D:  'Error  Handling" 

A  pp.  D:  "Error  handling" 

Chap.  2:  'Handle  Specific  Events" 

Chap.  4:  "Constructing  Dialog  Boxes..." 
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To  We  2-T  (continued) 

HodgePodge  routines  described  in  this  book 


Routfn« 


S««  chapter  ond  lecHon,.. 


DoChooseFont 

DoChooaerltem 

DoCloseltem 

DoMenu 

DoPrintltem 

DoSaveltem 

DoSetUpItem 

DoTheopen 

DrawTopWindow 

HodgePodge 

InitGlobala 

StartUptools 

LoadOne 

MainEventLoop 

MountBootDiak 

OpenWindow 

Paint 

Paintrt 

SaveOne 

SetUpDef ault 

SetUpMenus 

SetUpWindows 

ShowFont 

ShutDo wnTool 3 


Chap,  3:  "Drawing  to  the  Screen" 
Chap,  5:  "Communicating  With  FiJes 
Chap.  2:  "Handle  Specific  Events" 
Chap.  2:  'Handle  Specific  Events" 
Chap.  5;  "Communicating  With  Files 
Chap.  5:  'Communicating  With  Files.  .J 
Chap.  5;  "Communicating  With  Files.,.* 
Chap,  4:  "Creating  Windows"  | 
Chap.  5;  "Communicating  With  Files.,.' 
Chap.  2:  "Hodgepodge  n  a  Glance' 
Chap.  2:  "Start  the  Program"  | 
Chap,  2:  "Start  the  Program"  , 
Chap.  6:  "The  FroDOS  File  System"  i 
Chap.  2:  "Cycle  Through  the  JVIainEvenL" 
App.  D:  "Error  Handling"  ' 
Chap.  4;  "Creating  Windows" 
Chap.  2:  "HandJe  Specific  Events" 
Chap  3;  "Drawing  to  the  Screen" 
Chap,  6:  "The  ProDOS  File  System'  , 
Chap.  2.  "Start  the  Program" 
Chap.  2:  "Start  the  Program" 
Chap.  2:  "Start  the  Program" 
Chap.  3:  "Drawing  to  the  Screen" 
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The  comptefe  referenca  for  all 
fool  box  colls  is  Jh9  Appie  hgs 
Toolbox  RefBrence.infm 
volumes. 


In  Chapter  2,  the  sample  program  HodgePodge  showed  an 
example  of  toolbox  use  in  action.  Now  let's  examine  some  of  th^' 
concepts  behind  the  toolbox  calls  HodgePodge  makes.  Even 
though  an  introductory  book  like  this  can  only  get  you  started 
each  tool  set.  the  overall  view  of  whaL  the  tools  can  do  for  you 
and  the  example  of  how  HodgePodge  integrates  them  should  la 
you  a  long  way  toward  understanding  and  exploiting  their  power 
The  Apple  IIGS  Toolbox  is  made  up  of  about  30  tool  sm.  Each 

80O  toolbox  routines  in  ROM  and  RAM,  covermg  a  wide  varieEy  qf 
tasks  from  managing  memory  to  drawing  to  the  screen  to  Riviiit- 
you  the  time  of  day.  And  don't  worry-joii  neean't  memorize 
Ihemall  lo  wme  an  Apple  IIGS  application.  Just  the  few  you  learn 
Irom  this  book  will  get  you  started.  1 

You  can  think  of  the  toolbox  as  a  very  large  library  of  prewritten 
subroutines.  opunn..ed  and  integrated  to  relieve  you  of  a  large 
part  of  your  programming  burden.  They  exist  to  free  you  to 
concentrate  on  the  fundamental,  creative  aspects  of  the  pragram 
you  want  to  write.  *^  * 

In  this  chapter  we  discuss  events  and  how  to  handle  them,  and  I 
basic  process  of  drawing  to  the  Apple  liGS  screen  by  using 
QuickDraw  II.  Chapters  A  and  5  describe  the  remaining  tool  sets 
We  11  include  actual  examples  from  HodgePodge  wheFe 
appropriate,  but  otherwise  the  details  of  individual  calls  and  their 
parameters  are  left  for  other  books.  ^  tneir 


Starting  up  and  calling  the  tools 

Jr'.nh  ^  ^  ■ ^"^'^'^  ^'^'^  "''''■^^^  before  you  can  oil 
start  them  up  in  the  proper  order. 


Required  tool  sets  "  ' 

Apple  IIGS  Toolbox.  Start  them  first,  and  start  them  in  this  orde: 
1.  The  Tool  Locator 
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Ftefer  to  "Set  ttie  Stage'  in 
Chaptei  2  fo  see  how  closely 
HodgePodge  follows  this 
sequence. 


2  The  Memory  Manager 

3-  The  Miscellaneous  Tool  Set 

Beyond  these  ihnee,  there  are  two  other  tool  sets  that,  while  not 
absolutely  required  for  the  Apple  OCS  to  function,  are  nevertheless 
used  in  nearly  every  application.  Start  Ihem  up  in  this  order: 

4.  QuickDraw  II 

5.  The  Event  Manager 


Other  tool  sets 

After  the  required  tool  sets  are  in  place,  you  should  load  and  start 
up  all  other  tool  sets  your  application  might  use. 


Loading 

To  simplify  things,  and  to  ensure  that  the  correct  versions  of  tool 
sets  are  available,  it's  best  to  load  all  of  your  needed  tool  sets  at 
once,  with  the  Tool  Locator's  LoadTools  call-  LoadTools  does  two 
things;  it  loads  RAM-based  tools  into  the  computer  Cremembcr, 
some  tools  are  not  in  ROM),  and  it  checks  the  version  numbers  of 
all  the  specined  tool  sets,  whether  in  ROM  or  RAM.  That  version 
check  is  important  because  some  tool  sets  will  not  function 
without  the  proper  minimum  versions  of  other  tool  sets. 

When  you  make  the  LoadTools  call,  you  pass  it  a  pointer  to  a  tool 
Hodgepodge's  tool  table  Is  table,  which  lists  the  total  number  of  tool  sets  to  load,  and  the 

Inlttolked  In  tti 9  routine  number  and  minimum  acceptable  version  of  each  tool  set. 

SJQttUpTOOlS. 


Important    Make  sure  that  all  the  (^AM-based  tools  your  ptogram  ne&ds  are  In 
ttie  TOOLS  subdirectory  of  the  SYSTEM  directory  on  the  system  disk. 
foi  a  list  of  an  cu  rrsnt  tool  sets  ond       See  Append  ix  C , 

their  numbers,  see  'User  Tool   ,  ■  ^  

Sets'  In  Chapter  8. 

Starting  up 

After  you  have  loaded  the  remaining  tool  sets,  you  must  then  start 
up  each  one.  Each  tool  set  has  its  own  startup  call;  some  calls 
require  or  return  parameters,  others  have  no  inputs  or  outputs. 
Because  some  tool  sets  require  the  presence  of  other  tool  sets  in 
order  to  function,  tool  sets  must  be  started  in  proper  order.  Table 
3-1  gives  the  suggested  startup  order. 
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Table  3-1 

Tool  set  startup  order 


H9X. 

Dec. 

Name 

$01 

1 

Tool  Locator 

$02 

2 

Msruory  Msn^^cr 

$03 

3 

Miscellaneous  Tool  Set 

$04 

4 

QuickDraw  II 

$06 

6 

Event  Manager 

SOE 

14 

Window  Manager 

$10 

16 

Control  Manager 

$0F 

15 

Menu  Manager 

314 

20 

LineEdi:  Tool  Set 

$15 

21 

Dialog  Manager 

S05 

5 

Desk  Manager 

517 

23 

Standard  File  Operations  Tool  Set 

Sl6 

22 

Scrap  Manager 

$1C 

28 

List  Manager 

$13 

19 

Print  Manager 

$1B 

27 

Font  Manager 

You  can  assume  that  tool  sets  not  on  this  list  are  either  started  Bp 
already,  or  can  be  started  in  any  order.  i 

*  HodgcPodge:  You  may  have  noticed  that  HodgePodge  doesnl 
follow  this  sequence  exactly  when  it  starts  its  tool  sets. 
Specirically,  it  starts  up  the  Menu  Manager  is/ier  starting  the 
UneEdit  Tool  Set  and  the  Dialog  Manager.  So  in  some 
instances  it  may  be  possible  to  alter  startup  order  siighdy, 
is  safest  just  to  follow  the  order  given  in  Table  3-1. 

In  addition  to  the  dependencies  reflected  in  the  startup  order 
tool  sets,  there  are  additional,  complex  dependencies  among  tool 
sets  because  a  routine  in  one  tool  set  may  call  routines  in  othq 
tool  sets  (which  may  call  routines  in  still  other  tool  sets,  and  stt 
on).  These  dependencies  are  beyond  the  scope  of  this  book;  s 
the  individual  tool  set  and  routine  descriptions  in  the  Apple  E 
Toolbox  Reference. 
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Calling  an  individual  routine 

You  can  access  toolbox  routines  easily  from  either  assembly 
language  or  high-level  languages.  The  initial  languages  offered 
with  the  Apple  IIGS  Programmer's  Workshop  (APW,  described  in 
Chapter  7)  are  658 16  assembly  language  and  C;  macro  libraries 
and  interface  libraries  are  available  for  these  languages.  Any  other 
languages  with  similar  interface  libraries  (such  as  the  TML  Pascal 
used  to  write  the  Pascal  version  of  Hodgepodge)  allow  similar 
tool-calling  procedures. 


The  Tool  Locator  is  documented 
fully  undsi  "The  Too!  Locptof'  in 
flie  ApplQ  liGS  Toolbox 
fisferenca 


"me  Tool  Locator 

Every  time  you  make  a  tool  call,  your  request  goes  through  the 
Tool  Locator,  the  first  tool  set  started  up  at  Uie  beginning  of  your 
program.  The  Tool  Locator  (in  ROM)  keeps  tables  in  RAM  thai 
point  to  the  individual  routines  (which  may  be  in  either  ROM  or 
RAlM).  *Ihe  pointer  tables  are  kept  in  RAiM  so  liiat  they  may  be 
easily  modified  when  tool  sets  are  updated,  moved  to  ROM  from 
RAM,  or  otherwise  changed.  Your  application  needn't  know  or 
care  where  a  routine  is — it  just  tells  the  Tool  Locator  to  get  it, 


Calling  from  assembly  language 

The  simplest  way  to  make  tool  calls  from  assembly  language  is  to 
use  macros.  The  macros  provided  with  APW  relieve  you  of  having 
to  remember  the  tool  set  number  and  routine  number  for  each 
call.  Assembly-language  IlodgePodgc  makes  all  its  calls  with 
macros. 

Make  a  tool  call  as  follows: 

1.  If  the  function  has  any  output,  push  the  correct  amount  of 
space  for  it  on  the  stack. 

The  Input  and  output  parameters         2.  If  the  function  has  any  inputs,  push  them  on  the  stack  in  the 
tor  each  as$emblv-language  tool  specified  order, 

call  ore  desciibed  In  the  Apple 

IIGS  Toolbox  Reference  3.  Invoke  the  appropriate  macro  by  name.  A  macro  name  is  the 

same  as  the  routine  it  calls,  except  tliat,  by  convention,  it  has  a 
leading  underline  character. 

4  Check  for  errors,  as  described  under  'Machine  State  on  Return 
from  the  Call,"  later  in  this  section, 

5.  Pull  the  output,  if  any,  from  the  suck. 
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You  can  make  an  assembly-language  tool  call  without  macros, 
course.  The  meihod  is  almost  identical  to  that  just  described, 
except  that  instead  of  calling  the  routine  by  name,  you  jump  id 
the  Tool  Locator's  entry  point  ($U  1  0000)  with  a  JSL  instniction, 
with  the  tool  set  number  and  routine  number  as  the  high-order 
and  low-order  bytes  in  the  X  register.  All  tool  set  and  routine 
numbers  are  documented  in  the  Apple  IICS  Toolbox  Refsrence. 
Nevertheless,  it  is  probably  best  to  use  macros  because  names  are 
easier  to  remember  and  read, 


The  nomes  of  the  parameters  for 
each  tool  roullr^g  In  the  C 
languoge  are  described  in  the 
Apple  liss  Tootbox  Reference. 


Calling  from  a  high-level  languoge 

The  interface  libraries  that  allow  C  programmers  to  access 
Apple  IIGS  Toolbox  are  included  in  APW  C.  Those  libraries 
contain  the  function  definitions  for  the  tools.  The  steps  to  caltj 
routine  are  as  follows.  Other  high-level  languages  will  have ! 
libraries,  appropriate  to  the  languages'  structures. 

I  Make  the  routine  accessible  by  using  an  # include  stati 
that  includes  the  appropriate  file  (for  example,  QuickUra* 
for  QuickDraw  II  calls).  The  included  file  will  provide  the 
function  declarations  and  the  necessary  constants  and  data] 
structures. 

Z  Invoke  the  call  by  entering  its  name  and  supplying  the  corn 
parameters, 

3.  Examine  the  global  error  variable  (_toolErE  in  C, 
ToolErrorNum  in  Pascal)  for  errors,  if  necessary.  If  the 
variable  is  equal  to  zero,  no  errors  occurred;  otherwise,  it 
contains  the  number  of  the  error. 


For  a  complete  description  of 
[©Qfster  and  flog  states  after  a 
toolbox  caJ[,  see  'Using  the 
Apple  liGS  Tool  Sets'  in  tiie  Appia 
Toolbox  Peterence 


Machine  state  on  return  tronn  the  call 

When  it  completes  a  call,  a  toolbox  routine  returns  control 
directly  to  the  application  that  called  it.  Tlie  accumulator  conti 
zero  and  the  c  flag  (carry  bit)  is  cleared  to  zero  if  the  call  was 
completed  successfully.  Other  flags  and  registers  have  values 
dependent  on  the  specific  routine  called. 

If  an  error  occurred  during  the  call,  the  carry  bit  is  set  (-1) 
the  accumulator  contains  an  error  code  in  this  formal: 


high-order  byte 
low-order  byte  = 


=  tool  set  number 
error  number 
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❖  Error  passing:  With  thJs  mclhod,  an  error  can  be  properly 
All  toolbox  error  codes  afe  idcnUfied  even  if  it  occurs  during  a  call  to  one  tool  sci,  but 

iummQilied  in  on  appendix  to  doesn't  actually  show  up  until  i  call  returns  from  another  loot 

f^oXSrln^^  '^^  example,  using  this  method,  a  QuickDraw  II  call  can 

pass  on  an  error  message  from  the  Memory  xManager. 


Handling  events 

The  central  part  of  any  event-driven  program  is  iw  main  event 
loop.  As  Figure  2-5  shows  in  the  case  of  Hodge  Podge,  the  program 
continually  cycles  through  the  event  loop,  waiting  for  an  event  to 
act  upon.  The  application  decides  what  lo  do  from  moment  lo 
moment  by  looking  at  each  event  and  responding  lo  it 
appropriately. 

What  constitutes  an  event?  An  event  is  a  notification  lo  the 
program  that  something  has  occurred,  something  that  the 
program  may  wish  to  respond  to.  It  may  be  a  signal  from  outside 
the  program,  such  as  a  keystroke.  Or  it  may  be  something  internal, 
such  as  the  need  to  redraw  part  of  a  window  when  an  overlapping 
window  has  been  moved 

❖  Interrupts;  An  event  is  different  from  an  intermpt  in  that  it  is 
generated  in  software,  and  that  it  does  not  force  action  by  the 
application.  An  application  can  ignore  any  event  it  does  not 
need  lo  act  upon. 

The  Event  Manager  is  the  Apple  nos  tool  set  that  notes  these 
occurrences  and  records  them  as  events  (by  creating  event 
records).  For  example,  whenever  the  user  presses  or  releases  the 
mouse  button,  the  Hvent  Manager  records  the  action  in  an  event 
record.  The  Event  Manager  collects  events  from  a  variety  of 
sources  and  reports  them  to  the  application  on  demand,  one  at  a 
time.  The  F,vent  Manager  doesn't  necessarily  report  ihe  events  in 
the  exact  order  ihey  occur,  because  some  have  higher  priority 
than  others. 

The  Event  Manager  is  also  used  by  other  parts  of  the  toolbox.  For 
instance,  when  HodgePodge  calls  TaskMastcr  in  its  main  even: 
loop,  TaskMaster  in  turn  calls  the  Event  Manager.  See  'Using 
TaskM aster,"  later  in  this  section. 
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The  event  queue 

Most  events  are  placed  in  an  event  queue,  which  is  an  ordered  M 
of  event  records,  As  events  occur,  ihey  are  placed  at  one  end  of 
the  queue;  as  Ihe  application  cycles  Lhrough  its  event  Joop,  i[  pulfe 
events  off  the  oUier  end,  one  at  a  time,  by  making  a  call  such  as 
GetNextEvent. 

❖  TaskMasten  Rather  Ihan  call  GetNextEven:  direcLly,  wc  suggest 
that  your  application  call  TaskMaster  instead,  The  end  result, 
however  is  tlie  same — Taskmaster  calls  GetNextEvent,  which 
pulls  events  off  the  event  queue  as  usual.  See  "Using 
TaskMaster,"  later  in  this  section. 

Figure  3-1  shows  a  simplified  view  of  how  events  are  presented  to 
an  application.  All  event  types,  except  switch  events  and  the 
window-related  events  aciivate  &nd  update,  pass  through  the  eveitf 
queue.  The  various  types  of  events  are  ordered  by  priority  before 
the  application  sees  them.  Also,  the  application  can  filter  out,  or  I 
mask,  types  of  events  that  don't  apply  to  a  particular  situation. 


Appflcatfon- 
defined 
everts 


Desk 
Giccesory 
events 


Device 
driver 
events 

Keyboard 
events 

Mouse 
events 


■me 
nexteverf 


Ev«nl 
rvcord 


Window  Manager  evenits 
Cactivale.  update) 

Svirftch  events 


Figure  3*1 

Events  and  ftie  event  queue 
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Event  fypes 


Events  are  of  various  types.  Some  report,  actions  by  the  user; 
others  are  generated  by  the  Window  Manager,  device  drivers,  or 
Ihe  application  itself  for  its  own  purposes.  The  system  handles 
some  events  before  the  application  ever  sees  them,  and  it  leaves 
others  for  the  application  to  handle. 

Each  event's  type  is  described  by  an  event  code,  a  numeric  value 
that  the  Event  Manager  returns  to  the  application  getting  the 
event.  For  programming  convenience,  there  is  also  a  set  of 
predeRned  constants  for  these  codes.  Table  3-2  lists  the  codes  and 
constants,  The  first  half  of  the  TaskTable  in  the  assembly- 
language  version  of  HodgePodge's  main  event  loop  (in  the  file 
EVENT  .  ASM)  is  a  codfi  equivalent  to  Table  3-2;  C  and  Pascal 
Kodge Podge,  on  the  other  hand,  use  the  predefmed  constants  to 
describe  event  codes. 


Table  3-2 

Event  Manager  event  codes 


Valu* 

ConiFant 

Meaning 

0 

nullEvt 

null  event 

1 

mouseDownEvt 

mouse- down  event 

2 

mousetJpEvt 

mouse-up  event 

3 

keyDownEvt 

key-down  event 

4 

(undefined) 

5 

autoKeyEvt 

auto-key  event 

6 

updsteEvt 

update  event 

7 

(undefined) 

8 

activateEvt 

activate  event 

9 

switchEvt 

switch  event 

10 

deskAccEvt 

desk-accessory  event 

11 

drive rEvt 

device-driver  event 

12 

applEvt 

application-defined  event 

13 

app2Evt 

application-defined  event 

14 

app3Evt 

application-defined  event 

15 

app4Evt 

application-defined  event 
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From  Table  3-2  you  can  see  Lhat  16  is  the  msDcimum  number 
cases  your  main  event  loop  has  to  consider  if  your  applicattoti 
calls  GetNexlEvent.  If  it  calls  TaskMaster  instead,  many  of  thes^ 
events  are  handled  automatically;  however,  there  is  an  addici 
set  of  codes,  called  iask  codes,  returned  by  TaskMaster.  See 
TaskMaster,"  later  in  this  section. 

Event  records  and  masks 

Every  event  is  represented  by  an  event  record  containing  alt 
pertinent  information  about  that  event.  The  event  record  indu 
the  following  information: 

■  What!  the  event  code,  such  as  mouse-down 

■  When:  the  time  the  event  was  posted  Clhe  iick  cound 
m  Where:  the  location  of  the  mouse  at  the  time  the  event 

posted,  in  global  coordinates  (see  "Global  and  Loc^l 
Coordinate  Systems,"  in  this  chapter) 

■  Modifiers:  the  state  of  the  mouse  buttons  and  modifier  keysal 
Che  time  the  event  was  posted,  such  as  Option  key  doum 

u  Message:  any  additional,  event-specific  information,  such  as 
which  key  the  user  pressed  or  which  window  is  being  activated 

Some  of  the  Event  Manager  routines  can  be  restriaed  to  operate 
on  a  specific  event  type  or  group  of  types;  in  other  words,  some 
event  types  are  enabled  while  ail  others  are  disabled.  For  instance, 
instead  of  just  requesting  the  next  available  event,  the  application 
can  specifically  ask  for  the  next  keyboard  event.  It  does  so  by 
supplying  an  event  mask  as  a  parameter,  The  mask  disables  mf 
unwanted  event  types. 

There's  also  a  global  system  event  mask  that  controls  which  eveiil 
types,  the  Event  Manager  posts  into  the  event  queue  in  the  first 
place.  When  the  system  starts  up,  the  system  event  mask  is  set  to 
post  all  events. 


Responding  to  events 

Here  are  some  typical  application  responses  to  commonly 
occurring  events. 

<•  TasksMaster:  These  responses  apply  to  a  program  that  uses 
GeiNextEvent  in  its  event  loop.  If  you  are  using  TaskMaster 
instead,  see  "Using  TaskMaster,"  later  in  this  section. 
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Mouse  events 

Moi»se-down  and  mouse-up  events  occur  when  ihe  mouse  button 
is  pressed  or  released.  Mouse  movements  cause  the  cursor 
position  to  be  updated,  but  do  noi  create  events. 

On  receiving  a  nriou.se-down  event,  an  application  should  first  call 
the  Window  Manager  to  find  out  where  the  cursor  was  on  the 
screen  when  the  mouse  button  was  pressed,  and  then  respond  in 
whatever  way  is  appropriate.  Depending  on  where  the  cursor  was 
when  the  button  was  pressed,  the  application  may  have  to  call 
toolbox  routines  in  the  Menu  Manager,  the  Desk  Manager,  the 
Window  Manager,  or  the  Control  Manager. 

If  the  apphcation  attaches  special  significance  to  the  user  pressing 
a  modifier  key  or  keys  along  with  the  mouse  button,  it  can 
discover  the  state  of  the  modifier  keys  by  examining  the 
appropriate  flags  in  the  modifiers  field  of  the  event  record. 

If  you  want  your  application  to  respond  to  mouse  double-clicks,  it 
must  detect  them  itself.  It  can  do  so  by  comparing  the  time  and 
location  of  a  mouse-up  event  with  the  time  and  location  of  the 
mouse-down  event  immediately  following  the  mouse-up  event 

Mouse-up  events  can  be  significant  in  other  ways;  for  example, 
they  can  signal  that  the  user  has  stopped  dragging  the  mouse  after 
selecting  s  group  of  objects.  Most  applications,  however,  can 
ignore  mouse-up  events,  and  handle  dragging  with  other  calls 
such  as  TrackControl. 

❖  Hodgepodge:  HodgePodgc  does  not  need  to  respond  to  mouse 
events  directly.  See  "Using  TaskMaster,"  later  in  this  section. 

*  Altemalive  pointing  devices:  All  applications  that  use  the  Event 
Manager  work  with  alternative  devices  just  as  they  do  with  the 
mouse.  W'hen  a  device  such  as  a  graphics  tablet  is  being  u.sed, 
its  X-Y  location  and  button  status  appear  in  the  event  records 
in  place  of  the  mouse  information.  Mouse-up  and  mouse-down 
events  are  posted  when  the  alternative  device's  buttons  change 
state. 

Keyboard  events 

Key-down  events  occur  when  character  keys  are  pressed.  Modifier 
keys  (Shift,  Caps  Lock,  Control,  Option,  and  Apple)  generate  no 
keyboard  events  of  their  own — whenever  an  event  is  posted,  the 
state  of  the  modifier  keys  is  reported  in  a  field  of  the  event 
record.  The  character  keys  also  generate  auto-key  events  when  the 
user  holds  them  down. 
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For  a  key- down  event,  the  application  should  first  check  the 
modiners  field  lo  see  whether  the  character  was  typed  withfle 
Apple  key  held  down;  if  so,  the  user  may  have  been  choosingt^l 
menu  item  by  typing  its  keyboard  equivalent. 

If  the  key-down  event  is  not  a  menu  command,  the  application 
should  respond  to  the  event  in  whatever  way  is  appropriate,  For  | 
example,  if  one  of  the  windows  is  active,  the  application  coifid 
insert  the  typed  character  into  the  active  document;  if  none  of  i 
windows  is  active,  it  might  choose  to  ignore  the  event. 

Most  applications  can  handle  auto-key  events  the  same  way  they  | 
handle  key- down  events.  However,  you  may  want  your  appliatio 
to  ignore  au!0-kcy  events  that  invoke  commands  you  don't  want 
continually  repeated. 

❖  I lodgePodge;  The  only  key  events  in  HodgePodge  an?  the 
keyboard  equivalents  to  menu  commands,  TaskMaster  handlesl 
those  events  and  returns  the  menu-selection  information  to 
HodgePodge,  so  HodgePodge  itself  needn't  respond  to 
events  at  all. 


See  'Creating  Windows*  In 
Choptei  4  foi  Q  dfecusslon  of 
window  features, 


Window  events 

To  coordinate  the  display  of  windows  on  the  screen,  the  Window 
Manager  generates  activate  events  and  update  events.  Activate 
events  occur  whenever  an  inactive  window  becomes  active  or  an 
active  window  becomes  inactive-  Update  events  occur  when  ail  w 
part  of  a  window's  contents  need  to  be  drawn  or  redrawn,  usually 
as  a  result  of  the  user's  opening,  closing,  activating,  or  moving  a 
window. 

When  the  application  receives  an  activate  event  for  one  of  its  own 
windows,  the  Window  Manager  will  already  have  done  all  of  the 
normal  housekeeping  associated  with  the  event,  such  as 
highlighting  or  unhighlighting  the  window.  TTie  application  an 
then  take  any  further  necessary  action,  like  showing  or  hiding  a 
scroll  bar,  or  highlighting  or  unhighlighting  a  selection. 

On  receiving  an  update  event  for  one  of  its  own  windows,  the 
application  is  responsible  for  updating  (redrawing)  the  contents 
□f  the  window. 

❖  HodgePodgs:  Activate  and  updaie  events  in  HodgePodge  are 
handled  automatically  through  TaskMaster. 
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Other  events 

Device-driver  events  are  generated  by  device  drivers  in  certain 
situations;  for  example,  an  application  might  set  up  a  driver  to 
report  an  event  when  its  transmission  of  data  is  intermpted. 

A  desk  accessory  event  occurs  whenever  the  user  enters  the 
special  keysioke  CControl-Apple-Escape)  to  invoke  a  classic  desk 
accessory.  See  "Supporting  Other  Desktop  Features"  in  Chapter  5- 

An  applic3i[ion  can  define  as  many  as  four  application-defined 
events  of  its  own  and  use  them  for  any  purpose. 

Switch  events  are  reserved  for  fiiture  use. 

The  Event  Manager  returns  a  null  event  if  it  has  no  other  events  to 
report.  Most  applications  ignore  null  events  and  continue  through 
the  event  loop. 


For  o  full  discussion  of 
ToskMastar,  ses  'Window 
Manager'  in  the  Apple  lies 
Toolbox  RQfersnce 


Event  codes  are  listed  in 
Table  3-2, 


Window  regions  are  discussed 
under  "Creating  Windows'  in 
Chopte»4. 


Using  TaskMaster 

TaskM aster  is  a  routine  that  can  handle  m a r^y  standard  events. 
Technically,  it  is  part  of  the  Window  Manager,  and  it  handles 
window-related  events  such  as  drawing,  scrolling,  activating,  and 
updating  windows.  It  is  discussed  here  because  it  replaces  the 
GeLNexiEvent  call  for  an  application,  and  it  also  does  preliminary 
event-handling  for  mouse-down  and  key-down  events. 

When  your  program  calls  TaskMaster  instead  of  GetNexLEvent,  the 
following  happens: 

1.  TaskMaster  calls  GetNextEvent. 

2  If  no  evenl  is  ready  to  be  handled,  TaskMaster  returns  zero. 

If  an  event  is  ready,  TaskMaster  looks  at  it  and  tries  to  handle  it. 

If  Taskmaster  can't  handle  the  event,  it  returns  the  Event 
Manager  event  code  to  your  application.  The  application  can 
handle  the  event  as  if  the  event  were  coming  from  GetNextEvent, 

If  TaskMaster  can  handle  the  event,  it  calls  standard  toolbox 
functions  to  carry  out  the  task.  For  example,  if  the  user  presses 
the  mouse  button  in  an  active  window's  zoom  region, 
TaskMaster  detects  it  and  calls  TrackZoom;  it  then  calls 
ZoomWindow  if  the  user  actually  selects  the  zoom  region;  and 
finally  it  returns  no  event. 
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Wlien  calling  TaskMaster,  you  pass  a  pointer  to  a  TaskMaster 
record,  the  extended  task  event  record,  'llie  beginning  of  the  i 
is  the  same  as  an  event  record,  as  described  under  "Event  RecoriJ 
and  Masks,"  earlier  in  this  section.  When  TaskMaster  calls 
GetNextEvent,  it  passes  the  provided  pointer,  so  the  event  reC 
part  of  that  record  is  set  by  GctNcxtl-vent.  The  record  also  indu<i<»J 
a  task  mask,  similar  lo  the  event  mask;  it  tells  TaskMaster  wh 
types  of  events  to  handle. 

Sometimes  TaskMaster  can  handle  an  event  only  up  to  a  point.  lEll 
user  presses  the  mouse  in  the  active  window's  content  region.  Task- 1 
Master  detects  it,  but  won't  be  able  to  go  any  further,  so  it  tells  the 
application  that  a  mouse-down  event  occurred  in  the  active  - 
dow's  content  region,  and  lets  the  application  decide  what  to 
next. 

Because  it  only  partially  handle.?  some  events,  TaskMaster 
generates  its  own  set  of  "events"  that  a  program's  main  event 
loop  needs  to  respond  to.  Each  type  of  TaskMaster  event  his  a 
task  code,  a  numeric  value  that  Task^^ aster  returns  to  the 
application.  Just  as  for  the  Event  Manager  events  described  earlier 
in  this  section,  there  is  a  set  of  predefined  constants  for  these 
codes.  Table  3-3  lists  the  codes  and  constants,  The  second  half  of 
TaskTable  in  the  assembly-language  version  of  Hodgepodge's 
main  event  loop  (in  the  file  EVENT  .ASM)  is  a  code  representation 
of  Table  3-3;  C  and  Pascal  HodgePodge,  on  the  other  hand, 
the  predefined  corLstants. 

Note:  Many  of  these  task  codes  are  just  the  results  returned  1 
the  call  FindWindow,  which  TaskMaster  makes  after  calling 
GetNextEvent. 


Table  3-3 

laskMaster  task  codes 


Value 


16 
17 
18 
19 
20 
21 

23 


Constant 


Meaning 


wInDesk 
wInMenuBar 

wInContent 
wlnDrag 
wInGrow 
wInGoAway 
win Zoom 


in  the  desktop  area 
in  the  system  menu  bar 
(undefined) 

in  a  window's  content  region 
in  a  window's  drag  (title  bar)  regiofl 
in  a  window's  grow  (size  box)  regie 
in  a  window's  go-away  (close  box)  refST 
in  a  window  s  200m  (zoom  box)  region 
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24 


27 


26 


25 


23 


wInSpecial 


wInDeskltem 


wininf o 


wInFrame 


wInactMenu 


in  a  window's  information  bar 

in  the  special  menu  item  bar 
(predefined  items  in  the  Edit  menu) 

in  2  desk  accessory  menu  item  on  the 
Apple  menu 

in  a  window,  but  not  in  any  of  ihe 
above  parts  of  it 

in  an  inactive  menu  item 


$8xxx      wInSysWindow  in  a  system  Cdesk  accessory)  window 

Together.  Tabic  3-2  and  'I'able  3-3  show  that  TaskMaster  can  return 
lo  your  application  up  to  25  or  so  events  that  your  main  event 
loop  may  have  to  deal  with,  In  most  situations,  though,  TaskMaster 
handles  most  of  them  automatically,  HodgePodge,  as  we  saw  in 
Chapter  2,  responds  only  to  task  codes  17,  22,  and  25 
(wInMenuBar,  wlnGo Away,  and  wInSpecial). 

You  should  use  TaskMaster  for  at  least  two  reasons: 

□  It  can  help  you  get  an  application  running  as  quickly  as 
possible,  still  taking  advantage  of  the  standard  user  interface, 
TaskMaster  represents  one  of  the  steps  taken  to  remove  the 
most  tedious  user-interface  chores  from  the  application. 

□  TaskMaster  will  help  assure  upward  compaliblity.  New,  as  yet 
unknown,  features  may  be  added  to  the  Apple  IIGS  system  in 
the  future.  It  may  be  possible  to  incorporate  those  features  by 
modifying  TaskMaster  without  adversely  affecting  past 
applications.  In  other  words,  your  application  may  be  able  to 
use  new  features  without  any  modification  on  your  part. 


Drawing  to  the  screen  (and  elsewhere) 


Any  time  your  desktop  application  needs  to  draw  something,  it  uses 
the  Apple  IIGS  tool  set  QuickDraw  II  (and  its  extension,  QuickDraw 
II  Auxiliary).  QuickDraw  II  is  an  adaptation  and  exteasion  of  the 
Macintosh  toolbox  component  QuickIJ>raw — it  performs  similar 
operations  but  has  been  enhanced  to  support  Apple  IIGS  color. 

QuickDraw  11  allows  you  to  perform  graphic  operations  easily  and 
quickly.  QuickDraw  draws  text  in  dilTerent  fonts  with  styling 
variations  such  as  italics  and  boldface.  It  draws  lines  and  shapes 
of  various  sizes  and  patterns.  It  can  draw  items  in  a  variety  of 
colors  or  in  gray  scales. 
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p,|„f  Mo  ^,  ■  ^     ,^  QuickDraw  II  can  draw  to  the  screen  or  to  other  parte  of  Apple 

^n^eT -ComSi^ri^f  SSf^,,,  -emery.  I.  fact,  printing  .  document  with  the  Print  Manaa 

ond  Devices/  In  Chapler  S.  involves  using  QuickDraw  to  "draw"  your  document  into  a 

memory  buffer  used  by  the  Print  Manager. 

❖  Note:  For  brevity,  we'll  use  the  terms  QuickDraw  ^nd 
QuickDraw  U  synonymously  here  Unless  otherwise  expJic^ 
Slated,  QuickDraw  means  the  Apple  IIGS  tool  sets  QuickDm? 
and  QuickDraw  11  Auxiliary,  not  the  Macintosh  version,  jj 

To  get  our  bearings,  we'll  first  consider  where  QuickDraw  II  draw 
Then  we'll  bricfy  discuss  bow  it  draws,  and  finally  look  at  ivbati 
draws.  The  chapter  ends  with  two  examples  that  Ue  together 
several  of  the  key  ideas.  ' 


I 


Where  QuickDraw  II  draws 

The  question  of  u^ftere  QuickDraw  II  draws  involves  consideratioo 
of  Apple  IIGS  memory  Gncluding  screen  memory)  as  well  as 
QuickDraw's  own  internal  representation  of  its  drawing  universe. 
These  are  the  main  concepts: 

□  Drawings  are  stored  in  Apple  IIGS  memory  as  pixel  images, 
ordered  collections  of  bytes  that  represent  rectangular  rays 
of  pixels.  Screen  memory  contains  a  special  pixel  image-its 
contents  are  displayed  on  the  computer's  moniEor. 

□  QuickDraw  II  draws  its  text  and  graphic  objects  on  an  abstract tw 
dimensional  mathematical  .surface  called  the  coordinate  pMm 
Pomts  on  a  plane  are  much  easier  to  visualise  and  manipulate 
than  addresses  in  memory.  Locations  on  the  QuickDraw  U 
coordinate  plane  arc  related  to  pixel-image  memory  locations^ 
specific  location  information  supplied  to  QuickDraw. 

□  Quickdraw  draws  most  objects  within  the  context  of  graphic 
ports.  A  port  is  a  complete  drawing  environment  and  defines 
among  otJicr  things,  a  specific  part  of  memory  and  a  spcdiic" 
rectangular  area  on  the  coordinate  plane  where  drawing  cm 
occur,  There  can  be  many  open  ports  at  a  time— some  for 
drawing  to  the  screen,  .?ome  for  drawing  to  other  parts  of 
memory.  Different  ports'  drawing  spaces  may  be  separate  frtm 
each  other  or  they  may  overlap. 
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! 

(  □  QuickDraw  11  can  be  made  to  clip,  or  constrain  its  drawing,  lo 

within  limits  of  arbitrary  size,  shape,  and  location. 

□  By  manipulating  two  independent  sets  of  coordinates  iglobal 
coordinates  and  local  coordinates),  an.  application  can  easily 
control  both  what  gets  drawn  inside  a.  port's  drawing  space  and 
where,  on  the  screen  or  other  pixel  image,  that  drawing  space 
appears. 

The  coordinate  plon© 

QuickDraw  locates  every  action  it  takes  in  terms  of  coordinates  on 
a  two-dimensional  grid  (Figure  3-2).  The  grid  is  QuickDraw's 
coordinate  plane;  coordinates  on  the  plane  are  integers  ranging 
from  -16K  to  +16K  in  both  the  X-  and  Y-directions.  The  point 
C0,0),  therefore,  is  in  the  middle  of  the  grid.  Note  also  that  grid 
values  increase  to  the  right  and  downward  on  the  plane;  this  is 
different  from  what  you  might  be  used  to,  but  it  is  the  same 
direction  and  order  in  which  video  scan  lines  are  drawn. 

Distances  on  the  grid  are  measured  in  pixels.  Thus  a  10  x  10 
"square"  on  the  coordinate  plane  is  equivalent  to  a  rectangle  10 
pixels  by  10  pixels  on  the  display  screen  (which  would  not  be  a 
square,  of  course,  because  Apple  llGS  pixels  are  not  square),  Only 
a  very  small  portion  of  the  coordinate  plane  can  be  displayed  on 
the  screen  at  any  one  time— the  plane  is  32,000  pixels  on  a  side, 
'  whereas  the  screen  can  show  a  maximum  of  640  pixels  by  200 

pixels  at  a  time.  Figure  3-2  shows  the  approximate  size  of  the 
screen  (and  user)  compared  to  the  coordinate  plane. 


Impo riant    QuickDraw  rriLEt  not  be  asked  to  draw  outside  the  coordinate 
plane.  Commoncls  to  draw  outside  this  space  w\\\  produce 
unpredictable  resiJts,  They  won't  generate  errors. 


Macintosh  programmers:  This  conceptual  drawing  space  is  not 
the  same  size  as  that  used  by  QuickDraw  on  the  Macintosh.  On 
the  Macintosh,  the  drawing  space  is  64K  by  6AK  pixels  centered 
around  0,0,  thus  making  the  boundary  coordinates  -32K,-32k 
and  32K,32K. 
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■16.384 


-16.384 


+  16,384 

Ftgufe  3-2 

Tha  QuickDraw  II  coordlnote  plane 

To  understand  how  QuickDraw  does  its  drawing,  we  need  to  coimI 
how  it  represents  some  basic  graphic  elements.  On  the  coordinate 
plane,  grid  lines  are  considered  to  be  inRnitely  ihin.  A  point  ij 
defined  as  the  intersection  of  two  grid  lines,  so  it  also  has  no  _ 
dimensions.  Pixck,  on  the  other  hand,  have  a  definite  size;  they  ajB| 
thought  of  as  railing  between  the  lines  of  the  grid.  The  smallest 
elcmeni  that  QuickDraw  can  draw  is  a  pixel,  so  if  it  were  to  drawi 
point  at  the  location  G,3)  on  the  coordinate  plane,  it  must  draw  a 
single  pixel.  Dut  which  one?  Four  pixels  touch  the  point.  QuickDraw 
defines  the  pixel  corresponding  to  each  point  on  the  plane  as  the 
pixel  immediately  below  and  lo  (he  righl  of  the  point.  See  Figure  }-J 
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Figure 

Grid  lines,  paints,  ond  pixels  on  tine  coordirx^te  plane 


Pixel  images  and  the  coordinate  ptone 

A  pixel  image  is  an  area  of  memory  that  coritains  a  graphic 
image.  The  image  is  organized  as  a  rectangular  grid  of  pixels 
occupying  contiguous  memory  locations,  Each  pixel  has  a  value 
thai  delcrmines  what  color  in  the  graphic  image  is  associated  with 
thai  pixel. 

❖  Macintosh  programmers:  QuickDraw  ll's  pixel  images  are 
similar  to  Macintosh  QuickDraw's  bit  images.  The  major 
difference  is  IhaE  a  pixel  is  described  by  more  than  a  single  bit. 

As  described  above,  QuickDraw  II  draws  to  the  coordinate  plane. 
However,  the  coordinate  plane  is  really  just  an  abstract  concept. 
Inside  ihc  Apple  IlGS,  drawing  actually  occurs  by  modifying  pixel 
images — that  is,  by  modifying  the  contents  of  certain  memory 
locations.  In  particular,  drawing  something  visible  on  the  screen 
involves  modifying  the  contents  of  screen  memory. 

The  data  struaure  that  ties  the  coordinate  plane  to  memory  is  the 
Loclnfo  (for  location  information)  record.  The  Loclnfo  record 
tells  QuickDraw  where  in  memory  to  draw,  how  the  pixel  image  in 
that  part  of  memory  is  arranged,  and  what  its  position  on  ihe 
coordinate  plane  is.  In  Pascal,  the  Loclnfo  record  definition  looks 
like  Ihis: 


Loclnfo  -  Record 
portSCB 
ptrToPixlmage 
width 
boundsRect 

end 


Word 
Ptr 

Integer 
Rect 


Dra^\/lng  to  ttie  screen  (and  elsewlnere) 
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scan-line  control  byte  and 
m©  differences  befv/een  640 
mode  ond  320  mode  ore 
discussed  ftjrther  under  -Drawing 
In  Color,"  late;  in  thfs  section 


The  record  consists  of  four  fields: 

QuickDraw  how  many  b>l5  per  pixel  there  are  in  this 
,rT,ag.-two  for  640  mode,  four  for  320  mode. 

"  Cor  is  the  memory  addressi 

the  image points  :o  the  first  byte  of  ±e  pixel  imaTSh 
conta-as  ihe  first  Cuppcr-IcftmosO  pixel.  ^  '  ' 

It  can  teW  where  each  new  row  in  the  image  staru  Qhe 
image  width  must  be  an  even  multiple  of  8  hyteT' 
-  b^^ndsR.ct  Cfor  boundary  reaangle)  is  a  rectangle  that  mJ 
he  p,xel  image  onto  the  coordinate  plane.  The  upper  leftT' 
n  the  rectangle  corresponds  to  the  first  pixel  in  Xl^^ 
lower-r.ght  corner  of  the  rectangle  de.crLs  the  ™  oTd^^ 
P-el  .m.ge  (as  far  as  QuickDraw  is  concerned)  S^e  E^^f^' 


image  r— ^ 


image  widlti . 


Orlflin  -  (0,0) 


Boundary 
rectangJe 


tower  rl 
0627)  i 


Pixel  image  in  memofy- 


1  byte  (=  2  pixels  m  640  mods) 


Figure  3-4 

Pixel  imoge  and  boundary  rectangle 

^^^^ 

can  th  nk  nf  1   h     ''^^'^^^'^  r^'^t^^Ble  happens  to  be.  You 
Se  ^  "^'^^     ^^^'-^S     own  private  coS< 

completely 
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windows  Qfs  described  (urthei 
under  "CreatSng  Windows'  In 
Qiapt9r  A. 


GrofPorl,  port  rectangle,  and  clipping 

Most  drawing  lakes  place  in  conjunction  with  a  data  structure 
called  a  GrafPort  (for  graphic  port),  Each  GrafPort  contains  a 
complete  specification  of  a  drawing  environment,  including  the 
location  information  (Loclnfo  record)  described  above.  In 
addition  to  the  location  information,  a  GrafPort  contains  three 
other  fields  that  restrict  where  drawing  in  a  pixel  image  can  take 
place:  the  port  rectangle,  dipping  region,  and  visible  region. 

The  port  rectangle  (or  portEect)  is  a  rectangle  on  the 
coordinate  plane.  Any  drawing  in  a  GrafPort  occurs  only  inside 
its  portEect.  When  you  look  at  a  ivindow  on  the  screen  in  a 
desktop  application,  its  interior  (everything  but  its  frame) 
corresponds  to  a  port  rectangle. 

The  port  rectangle  can  coincide  with  the  boundary  rectangle  or  it 
can  be  different.  You  can  think  of  it  as  a  movable  opening, 
allowing  access  to  all  or  part  of  the  pixel  image,  As  Figure  3-5 
shows,  QuickDraw  can  draw  only  where  the  boundary  rectangle 
and  port  rectangle  overlap. 


Boundary  rectangle 


Port  rectangle  ■ 


Figu;e  3-5 

Boundary  rectangle/port  rectangle  fntersection 
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)  origin  of  a  recta ngfe,  in 
icliOraw  II.  Is  Its  upper-leff 
'ner. 


The  clipping  region  (or  clipRgti)  is  provided  for  an  application « 
use,  When  a  GrafPort  is  opened  or  initialized,  ihe  dipping  region 
is  set  to  the  entire  coordinate  plane  (effectively  preveming  mi- 
clipping  from  occuring).  The  program  can  use  the  dipRgn  in  any 
way  it  wants.  Any  drawing  to  a  pixel  image  through  a  GrafPort 
occurs  only  inside  the  clipping  region, 

The  visible  region  (or  visRgn)  is  normally  maintained  by  tlie 
Window  Manager.  An  application  can  have  multiple  windows  on 
the  screen,  each  one  assodated  with  a  GralPort.  Windows  can 
overlap,  and  each  port's  visible  region  represents  the  parts  of  ifie 
window  that  are  visible. 

In  summary,  drawing  occurs  in  a  pixel  image  only  in  the 
intersection  of  the  boundary  rectangle,  port  rectangle,  dipping 
region,  and  visible  region. 

Global  ond  local  coordinate  systems 

Everydiing  is  positioned  in  QuickDraw's  universe  in  terms  of 
coordinates  on  the  plane.  However,  if  you  think  of  multiple  open 
windows  on  the  screen,  you  can  see  that  there  are  at  least  two 
different  ways  in  which  you  might  want  to  locate  objects; 

O  You  may  want  to  specify  where  windows  appear  on  the  screefl 
(for  example,  when  they  are  moved), 

□  You  may  want  to  specify  where  objects  appear  within  windows 
(for  example,  when  scrolling),  independently  of  where  on  the 
screen  the  windows  may  be. 

❖  Hodgepodge:  Because  TaskMaster  takes  care  of  all  window 
events  related  to  tasks  such  as  moving  and  scrolling, 
Hodgepodge  itself  doesn't  worry  about  coordinates  at  all  when 
it  draws  a  window, 

The  toolbox  needs  global  coordinates  whenever  more  than  one 
Graft'ort  share  the  same  pixel  map;  the  global  coordinates  lei! 
QuickDraw  exactly  where  every  port  rectangle  is  compared  to 
every  other  one.  The  global  coordinate  system  for  each  Grafi^on 
is  that  in  which  tlie  boundary  rectangle  for  its  pixel  map  has  its 
origin  at  (0,0)  on  the  coordinate  plane.  For  drawing  to  the  screen, 
you  can  think  of  global  coordinates  as  screen  coordinmes,  where 
the  upper-left  corner  of  the  screen  is  the  point  (0,0). 
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However,  each  port  also  has  its  own  local  coordinate  system.  For 
example,  when  drawing  into  a  port  it  might  be  more  convenient 
to  think  in  lerms  of  distance  from  the  port  rectangle's  origin 
rather  than  ihc  boundary  rectangle's  origin.  By  defining  ihe  port 
rectangle  as  siariing  at  (0,0),  you  can  base  all  your  drawing 
commands  on  distance  in  from  the  left  edge  and  down  from  the 
top  of  the  porLRecl. 

Thai's  convenient  for  drawing  in  a  window,  but  local  coordinates 
are  more  of  a  convenience  than  thai.  They  aren't  constrained  to  a 
value  of  C0,0)  for  the  port  rectangle  origirj — you  can  set  them  to 
any  coordinate-plane  value.  Why  would  you  want  to?  Because  of 
the  way  drawing  commands  work. 

Suppose  you  are  using  a  window  to  display  portions  of  a 
document  that  is  larger  than  the  port  rectangle  in  size— a  fairly 
common  occurrence.  You  are  using  drawing  commands  that  draw 
the  entire  document,  and  you  know  that's  no  problem  because  the 
drawing  will  be  automatically  dipped  to  the  port  rectangle.  But 
how  do  you  control  which  part  of  the  document  shows  in  your 
window?  You  do  it  by  adjusting  local  coordinates. 

All  QuickDraw's  drawing  commands  are  based  on  the  current 
port's  local  coordinate  system.  So  if  location  (0,0)  in  your 
GrafPort's  local  coordinates  corresponds  to  the  port  rectangle's 
upper-left  corner,  any  time  you  draw  your  document  into  that 
port,  its  upper-left  corner  will  be  displayed.  If  you  define  your 
local  coordinates  differently,  different  parts  of  your  document  will 
appear  in  the  window.  Thus  you  can  think  of  local  coordinates  as 
document  coordinates — the  upper-left  corner  of  the  document 
being  viewed  in  the  port  has  the  value  (0,0)  in  local  coordinates. 
See  Figure  3-6. 
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Drows." 


Figure  3-6 

□rawing  differerit  por^s  of  a  document  by 
chonging  loco!  coordinates 

^  Note:  When  the  local  coordinates  of  a  GrafPorE  are  chai^^| 
the  coordinates  of  the  GrafPorl's  boundary  rectangle  and 
visible  region  are  similarly  recalculated,  so  (as  noted)  the] 
will  rot  change  its  relative  position  on  the  screen  or  in  td 
to  other  open  ports  on  ihe  screen. 

However,  when  the  loca]  coordinates  are  changed  the 
GrafPorl's  clipping  region  and  pen  location  are  not 
changed — that  is,  they  appear  lo  shift  right  along  with  the 
image  that  is  being  viewed  in  the  port.  It  makes  sense  to  have 
the  pen,  which  is  used  to  modify  ihc  image  being  viewed,  aM] 
the  clipping  region,  which  is  used  to  mask  off  parts  of  the 
image  being  viewed,  "stick"  to  it. 
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How  QuickDraw  II  draws 

How  QuickDraw  II  draws  any  of  its  objects  depends  on  the 
drawing  environmenL  specified  in  the  current  GrafPort.  Each 
GrafPort  record  includes  location  and  clipping  information 
(described  above),  information  about  the  graphics  pen 
(described  next),  information  about  any  text  that  will  be  drawn 
(described  under  "...And  Text  Too,"  later  in  thi^  section),  and 
other  information  such  as  pen  patterns  to  draw  with. 

The  drawing  pen 

Each  open  port  has  its  own  drawing  pen.  By  means  of  several 
characteristics  modifiable  by  the  application,  the  pen  controls 
where  and  how  drawing  (of  both  text  and  graphics)  occurs. 

Pen  locQfiofl:  The  pen  has  a  coordinate-plane  location  (in  local 
coordinates).  The  pen  location  is  used  for  drawing  lines  and  text 
only — other  shapes  are  drawn  independently  of  pen  location. 

Pen  »lz9:  The  pen  is  a  rectangle  thai  can  have  almost  any  width 
or  height.  Its  default  size  is  1  x  1  (pixels),  If  either  the  width  or 
height  is  set  to  0,  the  pen  will  not  draw, 

Pen  pattern:  The  pen  pattern  is  a  repeating  array  (8  pixels  by  8 
pixels)  that  is  used  like  ink  in  the  pen.  Wherever  the  pen  draws, 
the  pen  pattern  is  drawn  in  the  image.  The  pattern  is  always 
aligned  with  the  coordinate  plane  so  that  adjacent  areas  of  the 
same  pattern  drawn  at  different  times  will  blend  in  a  continuous 
manner. 

Background  paflern:  The  background  pattern  is  an  array  similar 
to  the  pen  pattern.  Erasing  is  the  process  of  drawing  with  the 
background  f>attern. 

□rowing  mask:  The  drawing  mask  is  an  8-bit  by  8-bit  pattern  that 
is  used  to  mask,  or  screen  off,  parts  of  the  pattern  as  it  is  drawn, 
Only  those  pixels  in  the  pattern  aligned  with  an  on  (=1)  bit  in  the 
mask  are  drawn.  Figure  3-7  shows  how  a  mask  affects  drawing  with 
a  pattern. 
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All  eight  pen  modes  (also  called 
transfer  modes)  cire  described 
and  diagrammed  under 
'OulclcDraw  11"  In  the  Apple  liGS 
Toolbox  Sfeletence. 


8x8  pattern 
with  masl<  applied 

■  ■  ■  ■  ['"'•I  i:"::":":::":" 

■  ■  ■  ■ 

Figure  3-7 

□rawing  with  pattern  and  mask 

Nole  lhat  drawing  with  a  mask  in  which  every  bit  has  ihe  value  1  ii 
like  drawing  wiili  no  mask  at  all — all  pen  pixels  are  passed  lirough 
lo  the  image.  Likewise,  drawing  wilh  a  mask  lhat  is  all  zeros  is  like 
not  drawing  at  all — all  pen  pixels  are  blocked. 

Pen  mode:  The  pen  mode  specifies  one  of  eight  Boolean 
operations  (COPY,  notCOPY,  OR,  nolOR,  XOR,  notXOR,  BIC  and 
noiDIC)  lhat  detern-une  how  the  pen  pattern  is  to  affect  an 
existing  image,  When  the  pen  draws,  QuickDraw  II  compares 
pixels  in  the  existing  image  with  their  corresponding  pixels  in  ihe 
pattern,  and  then  uses  the  pen  mode  to  determine  the  value  of  ihe 
resulting  pixels.  For  example,  with  a  pen  mode  of  COPY,  the 
existing  pixels'  values  are  ignored — a  solid  black  line  is  black 
regardless  of  the  image  already  on  the  plane.  Whh  a  pen  mode  of 
noiXOR,  the  bits  in  each  pen  pixel  are  inverted  and  then 
combined  in  an  cxclusivc-OR  operation  with  the  bits  in  each 
corresponding  existing  pixel.  Figure  3-8  shows  a  rectangle  drawn 
over  an  existing  circle,  in  both  COPY  and  notXOR  mode. 
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QjIckOrow's  shapes  are 
describ&d  neict.  undef  'What 
QJckDraw  II  Draws.' 


copy  mode  notXOR  mods 


Figure  ^-8 

How  pen  mode  affects  drawing 
Basic  drawing  functions 

QuicliDraw  draws  lines  with  the  current  pen  size,  pen  pattern, 
drawing  mask,  and  pen  mode. 

QuickDraw  draws  other  shapes  (rectangles,  rounded-corner 
rectangles,  ovals,  arcs,  polygons,  and  region^  in  five  different 
ways: 

■  Frame:  QuickDraw  draws  an  outline  of  the  shape,  usirig  the 
current  pen  sim,  pen  pattern,  drawing  mask,  and  pen  mode. 

■  Paint;  QuickDraw  fills  the  shape,  using  the  current  pen  pattern, 
drawing  mask,  and  pen  mode. 

■  Erase:  QuickDraw  fills  the  shape,  using  the  current  background 
patiern  and  drawing  mask, 

a  Invert:  QuickDraw  inverts  the  pixels  in  the  shape,  using  the 
drawing  mask. 

■  Fill:  QuickDraw  fills  the  shape,  with  a  specified  pattern  and 
using  the  drawing  mask. 

QuickDraw  draws  text  2.^  described  under  ".  ..And  Text  Too,"  later 
in  this  section. 
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What  QuickDraw  II  draws 


QuickDraw  II  can  draw  a  number  of  graphic  objects  into  i  pixel 
image.  It  draws  text  characters  in  a  variety  of  ntionospaced  and 
proportional  fonts,  with  styling  variations  that  include  italics, 
boldfacing,  underlining,  outlining,  and  shadowing.  It  draws  stts^ 
lines  of  any  length,  width,  and  pattern.  It  draws  hollow  orpattem- 
niled  rectangles,  circles,  and  polygons.  It  draws  elliptical  arcs  m 
filled  wedges,  irregular  shapes  and  collections  of  shapes.  It  also 
draws  pictures — combinations  of  these  simple  shapes.  Figure  3-9 
summarizes  them. 
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Figure  3-9 

What  QuickDraw  II  draws 


Points  and  lines 


A  point  is  represented  mathematically  by  its  Y-  and  X- 
coordinaics — two  integers.  A  line  is  represented  by  its  ends — two 
points,  or  four  integers.  Like  a  point,  a  line  is  infinitely  thin.  When 
drawing  a  line,  QuickDraw  II  moves  the  upper-left  corner  of  the 
pen  along  the  straight- line  trajectory  from  the  current  pen 
location  to  the  destination  location.  The  pen  hangs  below  and  to 
the  right  of  the  trajectory',  as  illu.strated  in  Figure  3-10. 
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Figure  3-10 

Drawing  lines 

Before  drawing  a  line,  you  can  use  QuickDraw  calls  to  set  the 
current  pen  locaiion  and  other  characteristics  such  as  pen  size, 
mode,  and  pattern. 


I  m  po  r  t  a  n  I    QuickDraw's  data  structure  that  defines  q  point  has  ttie  vertical 
ccordinote  first:  (y^>  rather  than  C>c.y). 


Rectangles 

A  rectangle  (Figure  3-11)  is  also  represented  by  two  points:  its 
upper-left  and  lower-right  corners.  The  borders  of  a  rectangle  are 
infinitely  thin.  Rectangles  are  fundamental  to  QuickDraw;  there  are 
many  functions  for  moving,  siEing,  and  □thcrw.ise  manipulating 
rectangles. 
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The  rectangJe  is 
defined  by  the  points 
0.2)  and  (7,6),  It 
encloses  24  pixels. 


OvQl  width 
Oval  height-^  \ 


Figure  3-11 

A  reclangle 

The  pixels  associated  with  a  rectangle  are  only  those  wUbin  Ux 
rectangle's  bounding  lines.  Thus  the  pixels  immediately  below 
and  to  the  right  of  the  bottom  and  right-hand  lines  of  the 
rectangle  are  not  part  of  il. 

Rectangles  may  have  square  or  rounded  corners.  The  cornets d 
rounded-corner  rectangles  are  sections  of  amis  (described  neiOll 
they  are  specified  by  an  ami  height  and  oual  width. 


Imporranf 


Tl^e  QuickDraw  data  strixihjr©  that  defines  a  rectangle  has 
coordinates  in  the  following  ordet:  top,  left,  bottom,  right.  ThLJsffie 
defining  coordinates  for  the  recfangla  In  Figure  3-1 1  are  <1 2J£}J 
may  seem  strange .  but  it  is  consistent  with  the  (y,x)  ordering  of 
points. 


Cifcles,  ovals,  arcs,  ond  wedges 

Ellipses  and  portions  of  ellipses  form  another  class  of  shapes 
drawn  by  QuickDraw  II.  An  oval  is  an  ellipse,  and  it  is  defined ju 
like  a  rectangle— the  only  difference  is  that  QuickDraw  is  told  to 
draw  the  ellipse  inscribed  within  itie  rectangle  rather  than  the 
rectangle  itself.  If  the  enclosing  rectangle  is  a  square,  the  resij 
oval  is  a  circle. 

*  Fixe!  shape:  Remember,  Apple  I  ICS  pixels  are  not  square.  A! 
circle  on  the  screen,  or  a  true  square,  will  have  unequal 
horizontal  and  vertical  dimensions  in  terms  of  pixels. 
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An  are  is  a  portion  of  an  oval,  defined  by  Lhe  oval's  enclosing 
rectangle  and  by  two  angles  (the  starting  angle  and  the  arc  angle), 
measured  clockwise  from  vertical. 

If  an  arc  is  painted,  filled,  inverted,  or  erased,  it  becomes  a 
wedge;  its  fill  pattern  extends  to  tfie  center  of  the  enclosing 
rectangle,  within  the  area  defined  by  the  lines  bounding  the  arc 
angle. 

Polygons 

A  polygon  is  any  sequence  of  connected  lines.  You  define  a 
polygon  by  moving  to  the  starting  point  of  the  polygon  and 
drawing  lines  from  there  lo  the  next  point,  from  that  point  to  the 
next,  and  so  on. 

Polygons  are  not  treated  in  exactly  the  same  manner  as  other 
closed  shapes  such  as  rectangles.  For  example,  when  QuickDraw  II 
draws  (frames)  a  polygon,  it  draws  outside  the  actual  boundary  of 
the  polygon,  because  the  line-drawing  routines  draw  below  and  to 
the  right  of  the  pen  locations.  When  it  paints,  fills,  inverts,  or 
erases  a  polygon,  however,  the  fill  pattern  stays  within  the 
boundary  of  the  polygon.  If  the  polygon's  ending  point  isn't  the 
same  as  its  starting  point,  QuickDraw  adds  a  line  between  them  to 
complete  the  shape. 

Regions 

A  region  is  another  fundamental  element  of  QuickDraw,  one  that 
can  be  considerably  more  complex  than  a  line  or  a  rectangle.  A 
region  can  be  thought  of  as  a  collection  of  shapes  or  lines  (or 
other  regions),  whose  outline  is  one  or  more  dosed  loops,  Your 
application  can  draw,  erase,  move,  or  manipulate  regions  just  like 
any  other  QuickDraw  structures. 

You  can  define  regions  by  drawing  lines,  framing  shapes, 
manipulating  existing  regions,  and  equating  regions  to  rectangles 
or  other  regions. 

Regions  are  particularly  important  to  the  Window  Manager,  which 
must  keep  track  of  often  irregularly  shaped,  noncontiguous 
portions  of  windows  in  order  to  know  when  to  activate  the 
windows  or  what  parts  of  them  to  update. 
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Pictures 


Pictures  are  used  for  Jronsferrlng 
data  between  opp I i cations,  via 
the  Cljpboofd,  See  'Scrap 
Manager'  In  me  Apple  IIgs 
Tootbox  Roferenca 


Text  models  sSmllai  to  pert  mode. 
discussed  eafller  in  this  section. 
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A  picture  is  a  colIecUon  of  any  QuickDraw  drawing  com 
data  scruclure  cotisisEs  of  little  more  lhan  ihe  stored  commarab 
QuickDraw  plays  the  commands  back  when  the  picture  is 
reconstructed  wiih  a  DrawPiciurc  call.  A  complex  mechanifial 
drawing  produced  from  an  Apple  liGS  drafting  program  rnight 
saved  as  a  single  QuickDraw  I]  picture. 


...And  text  too 

QuickDraw  II  doesn't  draw  graphic  images  only — it  also  does  all 
text  drawing  for  desktop  applications.  As  an  application 
programmer,  you  can  easily  control  the  placement,  size,  style, 
font,  and  color  of  display  text  with  QuickDraw  calls. 

Your  program  can  provide  QuickDraw  II  with  text  in  a  number  ol 
formats: 

■  character:  a  single  ASCII  character  al  a  lime 

■  Pascal  string;  a  length  byte  followed  by  a  sequence  of  ASCII 
characters 

■  C  string:  a  sequence  of  ASCII  characters  terminated  by  a  zero 

byte 

■  text  block:  an  arbitrary  number  of  ASCII  charaaers  in  a  buffer 

However  it  receives  the  text,  QuickDraw  II  draws  it  in  the  same 
way.  It  draws  each  character  at  the  current  pen  location,  with  the 
current  font,  using  the  current  text  mode,  with  the  current 
character  style,  and  using  the  current  foreground  and 
background  colors.  After  drawing  each  character,  QuickDraw 
updates  the  pen  location  for  drawing  the  next  one. 

Providing  QuickDraw  with  various  fonts  and  character  styles  [ 
job  of  the  Font  Manager,  The  Font  Manager  is  a  tool  set  that 
supports  QuickDraw's  character-drawing  ability  by  providing  an 
application  with  different  fonts  and  styled  variations  of  fonts, 
you  want  to  allow  the  user  to  choose  from  all  of  the  fonts 
available  when  the  application  Is  run,  or  If  you're  developing i 
application  that  requires  a  specific  font,  the  Font  Manager  cafl^ 
help  you. 
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Characters 

To  help  underscand  jusl  where  text  appears  and  how  much  space 
it  takes  up,  let's  derme  a  few  terms.  Refer  to  Figure  5-12. 

Text  fonts  are  made  up  of  individual  characters.  A  character  is 
represented  in  memory  as  a  rectangular  array  of  bits,  called  a 
character  image,  representing  rows  and  columns  of  pixels.  The  on 
C=l)  bit*  are  the  foreground  pixels;  the  oJfi=G)  bits  are  the 
background  pixels. 

Every  character  in  a  font  has  a  base  line.  The  base  line  is  a 

horizontal  line,  in  the  same  position  for  every  character  in  the 
font,  Any  foreground  pixels  of  a  character  image  that  lie  below 
the  base  line  consiimte  the  character's  descender  (characters  like 
p  and  q  have  descenders).  The  asceni  line  is  the  horizonial  line 
just  above  the  lop  row  of  a  character  (including  any  blanks);  the 
distance  from  the  base  line  to  ihe  ascent  line  is  the  font's  ascent, 
and  is  equal  to  the  height  of  the  tallest  characier  in  the  font,  l"he 
descent  line  is  ihe  line  just  below  the  bottom  row  of  the  character 
(including  any  blanks);  the  distance  from  the  base  line  to  tlie 
descent  line  is  the  font's  descent,  and  is  equal  in  size  to  the  largest 
descender  in  the  font. 

Bach  character's  origin  is  a  point  on  the  base  line  that  is  used  to 
position  the  character  for  drawing.  This  point  need  not  touch  any 
foreground  pixels  of  the  character  image.  When  the  character  is 
drawn,  it  is  placed  in  the  destination  location  so  that  its  character 
origin  coincides  with  the  current  pen  location.  For  many  letters, 
the  character  origin  is  located  on  the  left  edge  of  Ihe  character 
image;  then,  when  the  character  is  drawn,  its  leftmost  foreground 
pixels  fall  just  to  the  right  of  the  pen  location. 

The  font  height  is  the  sum  of  the  ascent  and  descent  heights,  and 
it  is  the  same  for  all  characters  in  a  font.  The  character  width  is 
the  number  of  pixels  the  pen  position  is  to  be  advanced  after  the 
character  is  drawn.  It  includes  the  width  of  the  character  itself  and 
any  needed  space  between  it  and  the  next  character  to  be  drawn. 

Font  height,  ascent,  descent,  character  width,  and  leading  (the 
space  between  lines  of  text)  are  needed  for  calculating  string 
lengths  and  line  spacings  when  you  display  text  on  the  screen. 
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Ffgure  3-12 

A  chofdcter  Image 
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The  b;isic  commands  necessary  lo  draw  characters  on  the  screen 
arc  qmie  simple.  Recall  hoa,  Chapter  2  how  HodgePodge  puts  up 
he  One  moment  please../'  message  when  the  program  loads 


MoveTo (20, 20) ; 

SatBackColor (0) 

S«tForaColor{15) ; 

Drawstring {' One  Moment  Please. 


(move  pen  to  upper  left  o£  screen} 
{background  color  -  blacl*} 
(foregroand  color  »  white] 
{write  the  me a sage J 


Once  the  foreground  and  background  coiors  are  set,  al]  that's 
needed  to  display  a  character  suing  is  to  move  the  pen  to  the 
desired  location,  and  caJl  ihe  QuickDraw  routine  DrawString. 

Fonts 

Each  collection  of  related  character  is  called  a  font.  With  the 
font  mampulation  capabilities  of  the  Font  Manager,  your  Apple 
IIGS  applications  can  show  sophisUcaied  text  display  in  a  varietv 
of  fonts,  sizes,  and  styles.  ^ 

Th*  fonf  strike.  All  the  character  images  making  up  a  font  are 
stored  in  memory  as  a  font  strike.  A  forrt  strike  is  a  long 
rectangular  array  of  bits  consisting  of  the  character  images  of 
every  defined  character  in  the  font,  placed  sequentially  in  order 

abut  eTch^r''^"         '^^  ^'"^^^^^  - 

abut  each  other;  no  blank  columns  are  left  between  them. 
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Figure  3-13 

Part  of  Q  font  strike 


Ih©  family  name  of  the  Apple  IBS 
^4^em  font  (in  ROM)  Is  Shaston 


A  given  font  strike  need  not  contain  a  character  Image  for  every 
possible  ASCII  code.  The  font  may  leave  some  characters 
undefinedi  these  are  called  missing  characters.  Immediately 
following  ihe  last  defined  character  in  the  font  strike  is  a  character 
known  as  the  missing  symbol,  which  is  to  be  used  in  place  of  any 
missing  character.  In  many  fonts  the  missing  symbol  is  a  hollow 
rectangle;  in  the  Apple  llGS  system  font,  it's  a  white-on-black 
question  mark.  Whenever  the  QuickDraw  0  text-handling  routines 
encounter  a  missing  character,  they  substitute  the  missing  symbol 
for  the  character. 

Choosing  a  font:  Fonts  for  the  Apple  IICS  are  grouped  into  font 
families.  Individual  fonts  within  families  can  have  vanous 
characteristics,  as  noted  in  the  following  list,  When  your 
application  requests  a  font,  the  Font  Manager  searches  all 
available  fonts  and  chooses  the  one  that  most  closely  matches  the 
request,  in  these  categories: 

■  Name;  Every  font  family  has  a  name.  The  name  refers  to  both 
plaia-styled  characters  of  all  sizes,  and  any  styled  variations, 
such  as  bold  or  italics. 

■  Number:  Every  font  family  has  a  numberj  also  independent  of 
point  sii:e  or  style  modifications.  Every  family  number  is 
unique,  and  corresponds  to  a  single  family  name,  $0000 
represents  the  system  font. 

Whenever  an  application  requtisls  a  font  whose  family  number 
is  not  available,  the  Font  Manager  substitutes  the  system  font. 

■  Size:  An  individual  font  has  a  size,  described  in  points,  A  point 
is  a  typesetting  measure  equal  to  about  l/72nd  of  an  inch. 
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The  Font  Manager  can  provide  boih  real  and  scaled  fonts  A 
real  fons  is  one  ihat  actually  exists  on  disk  at  a  particular  poii 
sjze.  Conversely,  a  scaled  font  is  one  that  was  enlarged  or  i 
reduced  by  calculaiion  from  a  font  of  a  differenl  size  The  Foi, 
Manager  may  scale  a  font  from  an  exisUng  si^e  if  the  requested 
si^c  IS  not  available,  Real  fonts  generally  have  a  better  screen 
appearance  than  scaled  fonts, 

■  Style!  An  individua]  font  also  has  3  style  Cor  combination  of 
styles).  The  presently  defined  styles  are 

□  Plain 

□  Bold 

□  Italic 

□  Underling 

□  Outline 

□  Shadow 

'ITiere  arc  two  different  ways  to  obtain  styled  variations  of  fod 
First,  the  Font  Manager  will  provide  a  styled  font  if  one  is 
available— one  whose  characters  are  designed  with  (for 
example)  bold  or  italic  styling.  Second,  QuickDraw  II  can  styla\ 
a  font^that  is,  it  can  produce  a  bold  or  italicized  version  of  af 
plain-siyled  font.  In  fact,  it  can  produce  any  combination  of  i 
defined  styles. 

❖  Note:  Fonts  that  are  already  st>'led  will  not  be  further  styled  fin 
[he  same  manner)  by  QuickDraw  11,  regardless  of  the  text 
stylmg  selected.  For  example,  an  italic  font  is  not  further  , 
Italicized  if  that  option  is  selected  on  a  style  menu.  However  it 
could  be  underlined  *  ' 

❖  UnderHmng:  Text  cannot  be  underlined  unless  the  font's 
characters  have  a  descent  value  (distance  between  the  base  lir 
and  descent  line)  of  at  least  2  pixels.  The  Apple  ITGS  system 
font  CShaston  8)  has  a  descent  value  of  1,  and  therfore  cannot 
be  underlined. 


Importon  t         Font  Manager  !aoks  for  fonts  fn  tho  subdirecto^  cQl!ed  FONTS/ 1 
Tnnfl?  ^  subdirectory  on  the  system  disk.  Thte  subdirectory  must 
con  am  all  fonfe  (except  the  systenn  font)  that  ore  to  be  available  to 
applications,  See  Appendix  C,  "  i^uje  to 
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DbChooseFont  is  In  the  source  file 
FONT.PAS. 


Your  application  can  allow  Lhe  user  to  select  a  font  by  calling  the 
Font  Manager  rouiine  ChooseFont,  That's  what  HodgePodge  does 
IniLsDoChooseFont  subroutine,  called  from  the  routine  DoMenu: 


{UBctiQli  DoChooaeFont:  Boolean; 

var       theFont       ;  Font  ID; 

duinny  :  Integer; 

tnii^'ort       :  GrafPortPtir; 

tmpPortRec :  Graf Port ; 

famNarne      :  Str255; 


(b^ijln  DoChooseFont—l 


isegin 


tmpPort  ;=  GwtPort; 
OpanPort  (gtmpE'ortRecl  ; 


theFont 


ChoosaFont.  (desiredFont.  ,  0)  ; 


if  Longint (theFont)  -  0  thsn 

DoChooseFont  :-  FALSE 
else 

-begin 

dfi3iredFont  theFont; 

dummy  :  ■  GatFamln  f  o  ( dDe  a  i  redFont .  f  amMuin , 

faniNiUTtei)  ; 

ir^Reply .  f  ilenajw  :  ■ 

concat  {f  aiTiNamei, 

IntToStrlng 

Idesiredf  ont .  f  ontsize) ) 
DoChooseFont  TRUE; 
end; 


Clo*aPort (JtmpPortRec) ; 
SatPort [tmpPort ) ; 


end/ 


{Save  current  port-l 

{„^d  open  new  one,   so  that 

the  current  port  is  not  affected} 
(Bring  Up  a  dialog  prompting 

the  user  to  select  a  font) 
{If  the  user  cancela„.) 
(tJoChooaeFont  unsuccessful} 


{Update  global  variable  CtesiredFont) 
{Get  the  font  name  from  its  nimber,.,) 

(„3nd  put  the  font  name  and  size  in.,,} 

(-.global  variable  myReply.filanajne} 
{DoChooseFont  completed  aucceas fully! 
{end  of  IF  user  doesn't  cancel} 

{Close  the  tainporary  port„.} 
{.,^d  restore  the  current  port} 
{End  of  DoChooseFont) 


ShowFort  is  iisted  undar 
"Olsplayirtg  Documents  In  Ports: 
Two  Examples,'  loter  In  this 
WCtlon. 


The  ShowFont  subroutine  in  HodgePodge  is  an  example  of  how 
to  draw  texi  surings  in  a  specific  font  with  QuickDraw.  It  is  called 
when  a  font  window  is  first  opened  and  also  whenever  it  needs  to 
be  redrawn. 
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Drawing  in  color 


The  video  display  hardware  of  the  Apple  IICS  includes  advanced 
color  capabilities.  Although  tool  calls  make  it  unneccessary  for 
you  to  manipulate  the  hardware  directly,  knowledge  of  a  few 
background  concepts  will  help  you  understand  the  way  QuickDraw 
II  manipulates  the  colors  on  the  screen. 

The  Apple  ilCS  offers  two  Super  Hi-Res  graphics  modes.  Botli 
modes  have  200  scan  lines,  but  the  scan  lines  differ  in  horizontal 
resolution — one  mode  has  320  pixels  (the  color  of  each  specified 
by  4  bits),  and  the  other  has  640  pixels  (the  color  of  each  specified 
by  2  bits).  In  changing  from  320  mode  to  640  mode,  the  horizontal 
resolution  is  doubled  at  the  expense  of  dividing  the  color  resold 
by  four. 

Both  modes  use  a  chunky  pixel  organization  (in  which  the  bits  for 
a  given  pixel  are  contained  in  adjacent  bits  within  one  byte),  as 
opposed  to  bit  planes  (in  which  adjacent  bits  in  memory-  affect 
adjacent  pixels  on  the  screen).  Therefore  the  4  bits  of  a  pixel  in  . 
320  mode  are  in  the  same  memory  locations  as  the  4  bits  of  a 
pair  of  adjacent  2-bit  pixels  in  640  mode. 

Colors  on  the  Apple  lies  are  determined  from  master  color  values, 
which  are  mathematical  combinations  of  the  primary  red,  blue,  «^ 
green  hues  available  on  a  color  monitor.  A  master  color  value  is  jt 
2-byic  number.  The  low-order  nibble  of  the  low-order  byte,  contrds 
the  iniensiLy  of  the  color  blue.  The  high-order  nibble  of  the  low- 
order  byte,  controls  the  intensity  of  the  color  green.  The  low-order 
nibble  of  the  high-order  byte,  controls  the  intensity  of  the  color  neSi 
The  high-order  nibble  of  the  high-order  byte  is  not  used.  Figure  3-ij( 
illustrates  the  format  of  a  master  color  value, 


Byte  1 


ByteO 


Bit: 

15  .  Id    13  1  12  1  1 

10    9  6 

7  1  6 

5  1  4 

3  1  2    1  '  0 

Value: 

(not  used)  | 

red 

green 

blue 

Figure  3-14 

Master  color  voiue  format 


A  3-digit  hexadecimal  number  can  describe  each  master  color, 
with  one  digit  (SO-SF)  for  each  primary  color.  Thus  a  master 
color  value  of  5000  denotes  black,  $FFF  is  white,  SOOF  is  the 
brightest  possible  blue,  $080  is  a  medium-dark  green,  and  so  on. 
Because  each  primary  color  has  16  possible  values,  a  total  of  4096 
colors  are  possible. 


I 
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At  any  one  lime,  ihe  Apple  IIGS  can  display  only  a  small  subset  of 
all  possible  colors.  An  application  specifies  its  colors  by 
constructing  one  or  more  color  tables,  short  lists  of  the  available 
colors  for  any  one  pixel. 

Color  tables  and  palettes 

ApplicaLions  cannot  specify  pixel  colors  directly  by  using  master 
color  values.  Pixels  contain  only  2  ojt  4  bits,  and  it  takes  12  bits  to 
specify  a  master  color  value.  Thai's  why  color  tables  are 
necessary.  A  color  table  is  a  table  of  l6  2-byie  enlries.  Each  entry 
in  the  table  is  a  master  color  value;  any  of  the  4096  possible  color 
values  may  appear  in  any  position  in  the  color  table. 

An  application  determines  the  color  of  a  given  pixel  by 
specifying  an  offset  into  the  color  table.  The  number  of  bits  used 
to  describe  a  pixel  limits  how  far  into  the  table  it  can  reach.  The 
colors  available  to  the  application,  as  specified  in  its  color  tables, 
constitute  its  palette.  See  Figure  3-15. 

Pixels  in  320  mode  are  n;prcsentcd  in  memory  by  4-bit  integers. 
For  each  pixel,  that  4-bit  value  is  used  as  an  offset  in  a  color  table. 
With  4  bits,  there  are  l6  possible  pixel  values,  so  tlie  palette  in  320 
mode  is  l6  colors — the  entire  color  table. 

Pixels  in  640  mode  are  represented  in  memory  by  2-bit  integers. 
With  2  bits,  there  are  4  possible  pixel  values  to  offset  into  the 
color  table,  so  the  palette  in  640  mode  consists  of  only  4  colors, 
That  would  seem  lo  leave  three-quarters  of  tlie  color  table  unused 
in  640  mode,  and  severely  restrict  the  use  of  color,  but  it's  not 
really  so. 

In  the  first  place,  each  4  adjacent  pixels  in  640  mode  use  4 
different  parts  of  the  same  color  table;  a  color  table,  then,  consists 
of  four  mini-paleUes,  which  needn't  have  the  same  sets  of  master 
colors.  Therefore,  although  each  individual  pixel  in  640  mode  can 
have  one  of  only  four  colors,  groups  of  four  pixels  can  have  a 
total  of  16  colors  from  which  to  choose.  How  lo  use  this  ability  to 
create  a  large  variety  of  colors  is  described  under  "Dithered 
Colors  in  640  Mode,"  later  in  this  section. 
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Paletle 


Color 
Table 

c 

n 
IJ 

1 

1 

4- 

5 

6 

7 

8 

10 

n 

12 

13 

14 

V 

15 

230 

mode 


ThQ  scan  line  conltol  byf©  Is 

cfiscussed  under  "The  Video 
Displays'  In  Itie  AppJe  Wqs 
Hardwafs  ffefefenceand  under 
■QuickDraw  inn  the  ApplQ  liGS 
Toolbox  Refer&ncB, 


pixel  =  4  bits 


Color 
Tabis 


Pixel  va(ue  = 
offset  into  tabi© 


(Moximurn 
value  =  15) 


r 

0 

Mlnl- 

1 

palette  3 

2 

•* — 

3 

4 — 

r 

4 

Mlni- 

5 

pQlette  4 

t 

7 

r 

3 

Mlnl- 
palette  l 

9 

10 

11 

r 

12 

Mini- 

13 

palette  2 

14 

V 

15 

1  pixel  =  2  bfls 


Pixel  volue  = 
offset  Into  table 

(Maximum 
value  =  3) 


640 
mode 


Figure  3-15 

Accessing  the  color  table  In  320-  and  640  mode 

An  application  may  construct  as  many  as  16  difTerent  color  tables 
to  choose  from.  Each  of  the  200  scan  lines  in  Super  Hi  Res 
graphics  can  use  any  one  of  the  16  tables.  For  each  scan  line,  a 
scan  line  control  byte  (SCB)  decides  which  color  table  is 
active.  The  SCB  also  controls  screen  display  mode  C320  or  640), 
interrupt  mode  (whether  or  not  lo  generate  an  interrupt  during 
horizontja  blinking),  and  fill  mode  (wticLhcr  or  nol  pixel 
values  of  2ero  can  be  used  to  fill  areas  of  color  in  320  mode). 


Standard  color  polette  (320  mode) 

The  standard  p:ileite  (the  default  color  table)  for  320  mode  is 
shown  in  Table  ^A.  In  the  table,  ojjmt  means  posiion  in  the  color 
table,  and  value  means  master  color  value,  the  hexadecimal  value  1 
controlling  the  fundamental  red-grcen-blue  intensities. 
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Tabia  3-4 

Standard  polette— 320  mode 


Color 


Value 


0 
1 
2 
5 
4 
5 

7 
8 

10 
11 
12 
13 
14 
15 


Black 
Dark  Gray 
Brown 
P  u  rple 
Blue 

Dark  Green 

Orange 

Red 

Beige 

Yellow 

Green 

Light  Blue 

lilac 

Periwinkle  Blue 
Lighl  Gray 
While 


000 
777 
84  1 

7  2C 
OOF 

08  0 
F70 
DOO 
TA9 
FFO 
O  E  0 
4  DF 
DAP 
7  8  F 
C  C  C 
PFF 


The  standard,  palelte  was  selected  because  of  its  flexibiliiy  and 
appearance;  we  recommend  Chat  you  use  it  unless  you  have  a 
specific  need  to  change  it. 

Dllhered  colors  in  640  mode 

As  explained  above,  only  four  colors  are  available  for  each  pixel  in 
640  mode.  But  when  small  pixels  of  different  colors  arc  next  to  eacl 
other  on  the  screen,  their  colors  blend.  For  exaniplc,  a  biack  pixel 
next  to  a  while  pixel  appears  to  ihe  eye  as  a  larger  gray  pixel.  By 
cleverly  choosing  the  entries  in  the  color  table  we  can  make  more 
colors  appear  on  ilie  screen.  This  process  is  called  dithering. 

At  the  same  time,  in  order  to  preserve  the  maximum  resolution  for 
displaying  text,  both  black  and  white  must  be  available  for  each 
pixel  This  leaves  only  two  remaining  colors  per  pixel  to  choose 
from,  which  seems  like  a  severe  restriction.  But  with  dithering,  you 
can  have  640-mode  resolution  for  text  and  stitl  display  16  or  more 
colors,  if  you  are  willing  to  resort  to  a  few  simple  tricks. 
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Consider  the  following  byte  with  four  pixels  in  it: 


BIf  value 
Rxel  number 


0  ;  ) 

0 : 1 

0 

I 

0;     T  1 

1 

2 

3 

4 

in  each  of  the  color  table's  minipalettes  (as  shown  in  Figure  MS 

rhi  .r  f  hT.T'^  '"^"^  '  minipalette  2.  and  so  on,  I  wew^ 
h.  standard  640-mode  color  tabic  (shown  in  Table  3-5)  then^S 

SDOO^  Th  ^^^'^^^       pixels  2  and  4  wHI  .ppe.r  ^ 

CSDOO).  The  eye  will  average  these  colois  and  see  violet. 

There  are  16  different  combinations  of  values  thsi  a  pair  of  nixJ. 
C.O  assur^  .n  640  mode,  meaning  that  you  can  obtafn  6  ol  f  ^ 
by  h  s  d^thcnng  method.  To  impiemer^t  it,  just  make  sure  that  the 


Table  3-S 

Standard  palette— mo  mode 


Co  tor 

Vatu* 

0 

Black 

0  00 

1 

Blue 

OOF 

2 

Yellow 

FFO 

3 

While 

FFF 

4 

Black 

0  0  0 

5 

Red 

D  0  0 

g 

Green 

0  E  0 

7 

White 

FFF 

8 

Black 

0  0  0 

9 

Blue 

OOF 

10 

Yellow 

FFO 

n 

White 

FFF 

12 

Black 

000 

13 

Red 

D  00 

14 

Green 

0  E  0 

15 

White 

FFF 

4 


<mfnipal«M«  offsef) 


0 
1 

2 
3 

0 
1 
2 
3 

0 
I 
2 
3 

0 
1 
2 
3 


I 
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❖  Black  and  white:  Note  that  the  envies  in  the  minipalettcs  for 
the  standard  640-mode  color  table  are  set  up  so  that  black  and 
white  appear  in  the  same  positions  in  each  palette.  This 
arrangement  provides  pure  black  and  white  at  full  640 
resolution,  allowing  crisper  text  display, 


Disploying  documents  in  ports:  two  examples 

Commonly  you  may  want  to  have  an  application  open  up  a  port 
and  display,  within  its  port  rectangle,  a  portion  of  a  previously 
created  drawing  or  text  document.  You  might  even  want  to  allow 
the  user  to  scroll  around  within  that  document,  showing  different 
parts  of  it  in  the  port. 

This  is  not  as  complicated  as  it  sounds.  We'll  just  give  you  a  brief 
idea  here  of  two  simple  ways  to  approach  it — two  of  the  methods 
used  in  HodgePodge.  Please  consult  the  Apple  IICS  Toolbox 
Reference  for  more  details.  See  also  "Creating  Windows"  in 
Chapter  4  for  more  information  on  scrolling, 

❖  Nots:  Ultimately,  you  are  likely  to  want  to  let  the  user  alter  a. 
part  of  a  document  while  viewing  it  in  a  port,  and  be  sure  that 
the  changes  made  are  reflected  in  updates  lo  the  document 
itself.  Hodgepodge  does  not  have  that  capability;  you  may  want 
to  add  it  as  a  programming  exercise. 

Plxel  images 

The  keys  to  displaying  a  portion  of  a  pixel  image  in  a  GrafPort  are 
the  QuickDraw  (and  QuickDraw  Auxiliary)  routines  that  copy 
pixels  from  one  region  lo  another.  One  is  CopyPixeb;  the  one  we 
use  here  is  PPToPort  (for  Paint-Pixels -to-Pori).  PPToPort  transfers 
pixels  from  a  given  source  pixel  image  to  the  current  GrafPort's 
pixel  image  (the  destination  pixel  image).  To  use  this  method  to 
view  a  document  you  might  try  the  following: 

1.  Define  a  Loclnfo  record  that  describes  the  offscreen  pixel 
image  you  wish  to  display. 

Z  Open  an  onscreen  GrafPort;  its  boundary  rectangle  is  the 
screen  image  boundary  rectangle,  Make  its  port  rectangle  any 
size  you  wish,  up  to  full  screen  si^se.  Now  anything  you  draw  Into 
that  port  will  be  visible  on  screen, 

3,  Set  your  port's  local  coordinates,  to  control  which  portion  of 
the  image  you  want  to  display  first,  To  show  the  upper-left 
corner  of  the  image,  set  the  port  rectangle's  origin  to  (0,0). 
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A.  Call  PP  to  Port  to  copy  I  he  offscreen  image  onto  the  onscreen 
rectangle,  The  call  asks  QuickDraw  to  draw  the  entire  image, 
because  drawing  is  automatically  clipped  to  the  port  rectangle 
you  only  get  the  part  you  waat. 

HodgePodgc  uses  PPtoPort  to  draw  the  contents  of  its  picture 
Polntit  Is  in  the  source  file  windows.  Here  is  the  routine  that  does  the  drawing  (Paintlt, 

PAINT. PAS  called  by  the  routine  Paint)  : 


;en 

e,  b 


procedure  Paintlt   (pict :  Handle) ; 

var        aircl/oc  :  Loclnfo; 
srcRect;  Rect; 

begin 

HLock (pict) ; 

with  srcLoc  do 
begin 

portSCB  :=  $O0SO; 

ptrToPiKlmaje  :=  pict"; 

width  160; 

S«til»ct  {boundsReet,  0,0,  640,200)  ; 

SetRoct {srcRect,  0,  0,  640,  200}  ; 

PPToPort (arcLoc, 

srcRact, 

Or 

0, 

arcCopy) ; 

HUnLoclt(pict)  ; 

end,- 


(begin  Paintlt...) 

(a  Laclnfo  record} 
(a  rectangle) 


(Lock  the  image's  meinoiy  bloclt) 

1  Define  the  Laclnfo  fields:) 

{set  640  mode} 
{pointer  to  the  image} 
{row-width  of  iirage  in  bytes) 
{boundary-rectangle  co-Drdinates} 

(rectangle  to  copy  n*OM) 

(Copy  pixels  from  this  Loclnfo...) 
(...and  this  source  rectangle^.) 
{„.to  location  (0,0)   in  the  current..,! 
{...GrafPort' a  local  coordinates...) 
{n^.with  a  pen  nK)de  of  COPY) 

(tJnlock  the  inage  now  that  we '  re  done} 
(End  of  Paintlt) 


Text  documents 

Many  documents,  such  as  text  Tiles,  have  no  explicit  pixel  image 
in  memory  that  represents  the  contents  of  the  file.  If  you  want 
your  application  to  permit  displaying  or  scrolling  through  audi  a. 
document  in  a  port,  you  wouldn't  transfer  pixels  from  one  image 
to  another — you  would  draw  directly  into  the  port  you  opened. 
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^  pljtel-based  Imoge  of  o 
document  as  seen  in  □  window  is 
commoniy  called  the  cfoto  area. 
See  'Cfeotlng  Windows"  in 
CSiaptef4. 


Stiowfont  is  in  the  sour cs  fii© 
FONT.  PAS. 


Nevenheless,  the  concept  of  local  coordinates  is  still  important 
and  is  used  identically.  Instead  of  using  an  actual  pixel  image 
somewKcre  in  memory,  you  need  to  calculate  a  "virtual  image"  of 
the  document  You  need  to  know  its  exact  size,  in  plxeh,  and  be 
able  to  place  it  properly  in  relation  to  tlie  port  rectangle  so  that 
the  part  you  want  displayed  is  within  the  rectangle,  llicn  you  can 
set  local  coordinates  accordingly  and  draw  the  document  to  the 
port,  knowing  that  it  will  be  dipped  appropriately, 

❖  Note:  Pascal  HodgePodge  calculate.";  document  height  when  it 
creates  a  text  window,  but  it  simply  assumes  a  parUcular  width. 
Assembly-language  and  C  versions  of  HodgePodge,  on  the 
other  hand,  calculate  document  width  also,  in  the  routine 
FindMaxWidth.  See  Appendixes  E  and  F. 

HodgePodge  calculates  line  height  in  pixels  and  locates  all 
drawing  in  relation  to  the  document  origin— point  (0,0)—  when  it 
displays  the  contents  of  a  font  window  using  the  routine 
ShowPont,  The  routine  first  installs  a  font  Goads  it  into  memory), 
then  calculates  line  height,  and  then  uses  that  information  to  draw 
ihe  text.  ShowFont  is  called  from  the  routine  DispFontWindow. 


-cedure  ShowFont (TheFontID:  FontID; 

IsMono;  Boolean)  ; 


fontlnfa  : 
currHeight ; 
if  J  • 

currPt 
fontSti 


FontlnfoRec; 

Integer,- 

Integer; 

Integer; 

Point  ,- 

Str255; 


{Begin  ShowFont...] 

{a  record  to  hold  font  information} 
(line  height  of  selected  font} 


(string  variable  to  hold,  characters  1 


begin 

Inatallfont  CTheFontlD, 0) ; 

GatFontlnfo  (f  ontlnf  oj  ,* 

currHeight  :=  fontlnfo .ascent  + 

font  Info. descent  + 
fontlnfo- leading; 

i  GstFjunlnfo  (TheFontlD.famNiur,  fontstr)  ,- 
fontStr        concat (fontStr, ' 

IntToString 

(TheFontlD. font size) > ; 

i  GatFijntFlaga; 

if  IsMfino  then 

i       BitQr(i, SOOOI> 
else 

i  :-  EitAnd(i, SOOOO) ; 
SatrontFIag«  Ci) ; 


(Load  the  font  into  iremory-.) 
(...and  store  its  data  in  Fontlnfo) 


{Calculate  the  font's  line  height} 
(Get  the  font's  name...) 


(..jnake  a  title  string  with 
font's  name  and  size} 
{Get  current  pano/prop.  setting) 
(If  menu  selection  says  "inono"..} 
(...set  bottom  bit  =  fixed  width) 
{Otherwise : ) 

{Clear  t»ttom  bit  =  proportional) 
(Store  result  in  font  flags) 


Drawing  fo  the  screen  (and  elsewhere) 
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WovmTo (S, currHeight) ; 
Drawstring {fontStr} ; 


(Now  draw  the  lines,  of  text:} 

[tfove  pen  to  start  of  first  line| 
(Draw  the  title  string} 


DrawStrina(  fl'>tip  a  line,  inove  to  start  of  next) 

■  ™,-\,  V.         ^      .  (Draw  aectwd  line} 
ine  quicJt  brown  fox  jumpa  over  the  lazy  doo.  "i - 

MovqTo  [5,corrHeight*ia)  ;  ^  " 

Drawstring  (  ,r,       ^i.  ^  ^  ,  . 

■  L  {Draw  third  line} 
iiiie  sells  sea  shells  down  by  the  sea  shore  ')  ■ 


MovaTo  (5,currH«ig[ht*5J  ; 
Jfor  i  :=  0  to  7  do 

GatPan  (currPtl ; 

MovftTo (5 , currPt .  V  +  currHeight)  j 
theCh       i  *  32; 
for  j        1  to  32  cfo 

fontStc[j:    :=  chr(theCh); 
Inc {thechj ; 
end," 

fOntStrfO]  :=  chr(32) ; 
Drawstring (f ontStr)  ; 


end,' 


mnd/ 


(Now  draw  all  characters  In  the  font 
fFor  each  of  7  lines...} 

(starting  at  current  pen  lDcation„.J 
{...drop  to  start  of  next  line) 
{...calculate  starting  character..} 
(For  each  of  32  chaca.  in  the  line...} 

(put  the  character  into  fort St r] 

(go  to  the  next  character} 

tend  filling  fontstr  for  this  line} 

{Now  set  the  length  byte  to  32...} 
(...and  draw  the  character  string} 

{end  of  drawing  tha  line} 
(End  of  ShowFont} 
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Chapter  4 


Using  the  Toolbox  (II) 


107 


This  chapter  continues  the  discussion  oF  the  Apple  IIGS  ToolbQX 
Starting  up,  handling  events,  and  basic  drawing  to  the  screen  were 
covered  in  Chapter  3;  here  we  look  at  tool  sets  that  help  you 
create  windows,  dialog  boxes,  and  alerts.  Chapter  5  presents  the 
remaining  tools. 


Th©  concepts  of  GralPonand 
port  rectangle  are  covered  In 
Chapter  3, 


1^ 

Creating  windows 

A  window  is  basically  a  pott  rectangle  with  a  frame;  when  you 
create  a  window  you  create  a  GraJPon,  along  with  some 
additional  inrormation  thai  makes  a  window.  When  you  draw  into 
a  window,  you  are  drawing  into  the  port  rectangle  of  the  GrafPqrt 
associated  with  that  window.  The  Window  Manager  is  tlie  Apple 
IIGS  tool  set  that  creates  these  "ports  with  frames,"  keeps  track  of 
their  characteristics,  and  makes  it  easy  for  you  to  deal  with  the 
fact  that  there  may  be  multiple,  movable,  scrollable,  overlapping 
windows  on  the  screen  at  any  one  lime. 


Window  basics 

To  begin  to  understand  windows,  let's  look  at  some  basic 
concepts,  specifically: 

□  how  windows  relate  to  GrafPorts 

□  what  data  structures  define  a  window's  features 

o  what  types  of  window  frames  and  controls  are  available 

□  what  window  regions  are,  and  how  the  content  region  oU 
window  relates  to  its  data  area 


Windows  and  GrafPorts 

It's  easy  to  use  windows — a  window  is  a  port  that  your  applicatiorr 
can  draw  into  conveniently  with  QuickDraw  II  routines.  When  you 
first  create  a  window,  the  pixel  image  and  boundary  reclangle'for 
its  GralPort  correspond  to  Ihe  entire  screen  (QuickDraw  U  s 
default  assignment),  and  the  pen  pattern  and  other  characEeri sties 
arc  also  the  default  values  for  a  Graff  ort.  You  can  accept  these 
default  characteristics  unchanged,  or  you  can  easily  change  them 
with  QuickDraw  II  routines, 
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For  examples  of  tt^e  use  of  these 
fields  In  HodgsPodgs,  see  ths 
lirtirngs  of  Point  or 

nspFonfWlrvdow  under  "HandlQ 
Epacitlc  Events'  iln  Chapter  2.  See 
alsottiQ  listing  of  the  routine 
DolheOpen,  under  "Opening  a 
Window;  An  Example.*  later  In 
ttds  section. 


But  there  is  more  to  a  window  than  the  port  in  which  ihc 
application  draws.  The  other  part  of  a  window  is  called  the 
window  frame.  It  usually  surrounds  the  window,  and  is  not  part  of 
the  window's  GrafPort.  You  don't  draw  into  the  window's  frame 
area  directly— the  Window  Manager  takes  care  of  that. 

❖  Note:  For  drawing  window  frames,  the  Window  Manager  uses  a 
GrafPort  that  has  the  entire  screen  as  its  port  rectangle;  this 
GrafPort  is  called  the  Window  Manager  port. 


Window  records  and  templates 

The  Window  Manager  keeps  all  the  information  it  requires  for  its 
operations  on  a  particular  window  in  a  window  record.  The  record 
consists  of  the  window's  GrafPort  record  plus  other  information 
the  Window  Manager  needs  to  manage  windows.  Application 
access  to  record  information  is  restricted  to  calk  through  the 
Window  Manager  and  directly  to  the  GrafPort  part  of  the  window 
record.  As  in  the  case  of  any  toolbox  records,  accessing  their 
fields  through  calls  instead  of  reading  ihem  directly,  helps  to 
guarantee  that  your  application  will  remain  compatibile  witli 
future  toolbox  revisions. 

When  you  create  a  new  window  with  the  NewWindow  call,  you  pass 
the  Window  iManager  a  NewWindow  parameter  list,  a  template  that 
defines  the  details  of  the  window  to  be  created,  including  its  si^e 
and  location  and  what  controls  it  will  have.  The  Window  Manager 
uses  this  information  to  construct  the  window's  record.  Three 
fields  in  the  NewWindow  parameter  list  are  worth  specific 
mention: 

□  wFrame,  a  set  of  bit  flags  thai  controls,  among  other  things, 
whether  the  window  is  to  have  frame  scroll  bars.  Simply  by 
setting  bits  in  this  field,  HodgePodge  specifies  that  its  windows 
are  to  have  both  horizontal  and  vertical  scroll  bars. 

□  wRefCon,  which  can  have  any  contents  an  application  wants. 
I-IodgePodge  uses  this  field  to  store  a  pointer  to  information 
abouE  the  type  of  window  (font  or  picture)  being  created, 

□  wContDef  proc,  which,  if  nonzero,  contains  a  pointer  to  a 
routine  (deflnitioo  procedure,  or  tie/Prod)  that  draws  the 
contents  of  the  window.  HodgePodge  stores  pointers  to  the 
routines  Paint  or  OispFontWindow  in  this  field. 
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Window  frames  and  controls 

There  are  Iwo  kinds  of  predefined  window  frames,  document  and 
alert.  Figure  4-1  lUusiraEes  tfiem. 


Document  window  frame 

Figure  4-1 

Window  frames 


AJert  window  ftome 


Som^B  of  the  standard  window 
parts  are  controls.  Controls  are 
dsscribad  in  moie  detail  In  the 
following  sactlon,  "Putting 
Conftols  In  Windows,' 


Clicking  refers  to  pressing  and 
releasing  the  mouse  button  while 
ttie  mouse  pointer  Is  stationary  on 
the  screen, 


Dragging  refers  to  pressing 
the  mouse  button  to  select 
something  and  holding  the  button 
down  while  moving  the  mouse, 


The  alert  window  is  used  by  ihe  Dialog  Manager;  see 
"Consiructing  Dialog  Boxes  and  AlerLs,"  later  in  ihis  chapter.  The 
documem  window  is  what  an  application  typically  uses.  Inside  a  ij 
document  window  carr  be  standard  window  parts,  which  indude 
[he  following: 

■  Tide  bar,  a  rectangle  at  the  top  of  the  window  that  displays  the  {  I 
window's  tide,  may  hold  the  close  and  ?.oom  boxes,  and  may  ' 
be  a  drag  region  for  rnoving  the  window, 

>  Close  box  Cgo-away  box),  a  small  square  in  the  title  bar  that 
the  user  clicks  on  to  remove  the  window  from  the  screen. 

■  Zoom  box,  a  small  square  in  the  title  bar  that  the  user  dicks  on 
to  alternately  make  the  window  its  maximum  size  or  return  it  to 
its  previous  size  and  position. 

■  Right  scroll  bar,  a  rectangle  on  the  right  side  of  the  window  that 
the  user  manipulates  to  scroll  vertically  through  the  data  shown 
in  the  window. 

■  Bottom  scroll  bar,  a  rectangle  at  the  bottom  of  the  window  that 
the  user  manipulates  to  scroll  horizontally  through  the  data 
shown  in  the  window. 

■  Size  box,  a  small  square  at  the  lower-right  corner  of  the 
window  that  the  user  drags  to  change  the  size  of  the  window, 

■  Information  bar,  a  rectangular  area  where  the  application  cao 
display  information  that  won't  t>e  affected  by  the  scroll  bars. 
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These  standard  parts  may  be  used  in  document  windows  only; 
they  may  not  be  added  to  alert  windows.  They  are  illustrated  in 
Figure  4-2. 


Title  bar 
 I  


Close  box 


Irformation  bar 


Window  Mat 


Content 


0 


I 

Boflom  scroll  bar 


Figure  4-2 

Standard  window  controis 


0 


o 


Zoom  boK 


—  Right  scroll  bor 


Size  box 


I 


Color  in  on  application  should  be 
designed  corefuHy.  Pleosg  refer 
to  Human  fnisrtacQ  Gi^deSnss: 
The  Appis  Desktop  Interfacelot 
iUQgestions. 


I 


It'i  possible  to  define  your  own 
type  of  window,  sucti  as  round  or 
hexagonal.  Bee  Ihe  Apple  HGS 
TootSox  Referencs  for  more 
jnlomiatlon. 


A  document  window  may  have  any  or  all  of  the  standard  window 
parts  The  only  restrictions  are  that  if  there  is  a  close  or  zoom  box, 
there  must  also  be  a  title  bar,  and  if  there  is  a  size  box,  there  must 
also  be  a  vertical  scroll  bar.  Common  sense  suggests  that  there  be 
a  zoom  box  if  there  is  a  size  box,  but  this  is  not  a  requirement. 

❖  Color:  You  can  specify  the  colors  of  the  frame  and  controls  of 
a  window  you  create.  Colors  are  selected  from  a  color  table. 
See  "Window  Manager"  in  the  Apple  lies  Toolbox  Reference 
for  details. 

You  can  use  the  standard  window  types,  or  you  can  create  your 
own  window  types.  Some  windows  may  be  created  indirectly  for 
you  when  you  use  other  parts  of  the  toolbox — for  example,  the 
Dialog  Manager  creates  a  window  to  display  an  alert.  Windows 
created  cither  directly  or  indirectly  by  an  application  are 
collectively  called  applkation  windows.  There's  also  a  class  of 
windows  called  system  windows;  those  are  the  windows  in 
which  desk  accessories  are  displayed. 
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A  rag/on  is  q  grophlc  object 
defined  by  QuIckDrow  II.  See 
"Drawing  to  the  Sc<een'  in 
Chapter  3. 


The  routines  Palntit  and  ShowFont 
In  Chapter  3  Siow  how 
Hodge  Podge  represents  the 
data  areas  of  Its  windows. 


How  scrolling  Is  accomplished  is 
described  later  In  this  section 
under  "Handling  Wlndow- 
Reloted  Events.' 


Content  region  and  data  area 

A  window  is  composed  of  regions.  The  window  as  a  whole  (the 
structure  rej^on)  is  made  up  of  the  content  region  and  the  Jrartx 
region: 

O  The  content  region  is  bounded  hy  the  rectangle  you  specify 
when  you  aeate  the  window  (that  is,  the  port  rectarrgle  of  the 
window's  GrafPort),  The  content  region  is  where  your 
application  presents  information  to  the  user. 

□  Ttre  frame  region  is  the  rest  of  the  window,  It  may  include 
several  subregions  that  correspond  to  the  locations  of  the 
standard  window  parts  described  earlier,  ^'hen  the  user 
manipulates  a  certain  control,  the  Window  Manager  sees  it  as 
an  event  occurring  in  a  certain  subregion.  See  "Handling 
Window-Kelated  Events,"  later  in  this  section. 

The  content  region  of  a  window  is  what  the  user  "sees"  within  the 
window.  It  commonly  represents  a  larger  area,  containing  more 
information  than  the  screen  can  display  at  one  time.  The  windoilSt'l 
is  then  like  a  microfiche  machine — what  is  seen  at  any  one  time 
in  its  content  region,  like  what  is  seen  in  a  microfiche  viewer, 
might  be  only  a  small  portion  of  the  window's  entire  data  area,  (J^ 
equivalent  to  the  microfiche  sheet. 

The  data  area  is  a  pixel-based  "picture"  of  whatever  document  isl 
being  displayed  in  the  window.  For  a  pixel  image  (such  as  a 
Hodgepodge  picture  file),  the  data  area  is  the  pixel  image  itself. 
For  a  text  document  (such  as  a  HodgePodge  font  window  display 
the  data  area  is  a  conceptual  representation  of  what  the  docume 
would  look  like  if  it  were  a  pixel  image.  The  document  doesn't 
exist  in  thai  form  anywhere;  the  appropriate  parts  of  it  are 
calculated  and  drawn  in  the  window's  GrafPort  each  time  the 
window  is  drawn  or  updated. 

Scroll  bars  are  the  controls  used  to  scroll  the  data  area  through 
the  content  region  of  the  window.  The  size  box  and  zoom  box  i 
used  to  display  more,  or  less,  of  the  data  area  at  one  time.  When] 
the  window  as  a  whole  is  moved  to  another  locadon  on  the 
screen,  the  data  area  is  moved  with  it,  so  the  view  in  the  content 
region  remains  the  same. 
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Figure  A-i 

A  window  dlsptays  port  of  lis  data  area 


A  window's  plan*  \z  Its  front-fo- 
bock  portion  on  th&  screen,  in 
relation  to  othsf  windows 


Handling  window -related  events 

The  Window  Manager's  principal  function  is  to  keep  iradc  of 
overlapping  windows.  Your  application  can  draw  in  any  window 
without  running  over  onto  windows  in  front  of  it.  You  can  move 
windows  to  different  places  on  the  screen,  change  their  plane,  or 
change  their  size,  all  without  coricern  for  how  the  various  windows 
overlap.  The  Window  Manager  keeps  track  of  any  newly  exposed 
areas  and  provides  a  convenient  mechanism  for  you  to  ensure 
that  they  are  properly  redrawn. 

There  arc  two  ways  to  handle  user  input  in  relation  to  windows. 
You  can  poll  the  user  with  the  Event  Manager  routine 
GeLNexLEvcnt,  or  with  the  Window  Manager  routine  Taski^laster, 
which  handles  most  events  dealing  with  standard  user  interfaces. 
See  "Using  TaskMaster™  in  Chapter  3. 
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Compare  these  results  from 
RndWindow  with  the-  TastoMasf  er 
task  codes  In  Table  3-3, 


If  you  are  using  GetKcxtEvcnt,  you  should  call  FindWindow  eve 
time  a  mouse-down  eveni  occurs,  to  see  if  the  mouse  button  was 
pressed  inside  a  window,  The  FindWindow  call  determines  whidi 
region  is  affected,  and  returns  the  information  to  you.  The 
following  are  the  various  subregions  recognized  by  FindWindow, 
and  the  standard  actions  to  lake  in  each  case. 

□  The  content  region  has  already  been  described.  If  the  mouse 
button  is  pressed  in  a  window's  content  region,  call 
SelectWindow  if  llie  window  is  not  the  active  window,  Otherwia, 
handle  the  event  according  to  your  application. 

□  The  drag  area  corresponds  to  the  window's  title  bar  (except  for 
the  close  and  zoom  boxes,  if  present).  Dragging  in  this 
subregion  pulls  an  outline  of  the  window  across  the  screen, 
moves  the  window  to  a  new  location,  and  makes  it  the  active 
window  (if  it  isn't  already). 

If  the  mouse  button  is  pres.sed  in  a  window's  drag  region,  call 
DragWindow. 

O  The  go-away  area  corresponds  to  the  dose  box  in  the  windawi 
title  bar.  Clicking  in  this  subregion  closes  the  window. 
Depending  on  your  application,  the  window  may  disappear 
permanently  or  simply  become  hidden. 

If  the  mouse  button  is  pressed  in  the  active  window's  close  boi 
call  Track GoAway.  If  TrackGoAway  returns  TI^UE,  call 
CloseWindow,  or  HideWindow,  perhaps  after  saving  whatever ' 
the  user  was  working  on  Inside  the  window.  You  may  also  waiU 
to  close  any  disk  file  associated  with  the  closed  window. 

O  The  zoom  area  corresponds  to  the  zoom  box  in  the  window's 
title  bar.  Clicking  in  this  subregion  toggles  between  the  current 
position  and  size,  to  a  maximum  size  and  back  again. 

If  tire  mouse  button  is  pressed  in  the  active  window's  zoom 
area,  call  TrackZoom.  If  TrackZoom  returns  TRUE,  call 
ZoomWindow, 

□  The  grow  area  corresponds  to  the  size  box  in  the  window's 
lower-right  corner.  Dragging  in  this  region  pulls  the  lower-ri 
corner  of  an  outline  of  the  window  across  the  screen  with  the 
window's  origin  fixed,  and  then  resizes  the  window  when  the 
mouse  button  is  released. 

It  the  mouse  button  is  pressed  In  the  active  window's  grow  are 
call  GrowWindow,  When  the  button  is  released,  call 
Size  Window. 


1)4 


Chcpter^l;  Using  the  Toolbox  < II) 


□  The  menu  bar  is  not  a  window  subregion,  but  a  result  returned 
by  FindWindow  that  means  "not  on  the  deskiop," 

If  the  mouse  butlon  is  pressed  somewhere  outside  ihe  desktop, 
it  is  most  likely  in  the  system  menu  bar.  Call  MenuSeleci, 

4*  Inactive  window:  Clicking  in  any  region  (other  than  the  drag 
region)  of  an  inactive  window  should  have  no  effect  other  than 
making  it  the  active  window.  It  is  brought  to  the  front  and 
highlighted  to  indicate  that  it  is  active. 

❖  TaskMasier-  If  you  are  using  TaskMaster,  it  calls  FindWindow  for 
you,  It  also  calls  MenuSelect,  DragWindow,  TrackGoAway,  or 
other  appropriate  calls  depending  on  the  results  of 
FindWindow,  In  general,  you  needn't  handle  any  window- 
related  mouse  events,  except  possibly  in  the  content  region  of 
an  active  window.  TaskiMaster  may  not  know  what  you  want 
drawn  in  an  active  window. 


Drawing  or  redrawing  a  window 


The  vts;w&  f&g/on is  rhe  portion  of 
a  window  that  b  not  offscr sen  or 
hidden  by  other  windows,  (t  is  one 
ofttie  Beldsin  a  GrafPortthot  clips 
drawing  commands-  See 
'Drawing  to  the  Screen"  in 
Ctiapt©r3, 

Tha  updato  region  ts  the  portion  of 
a  window  fhot  needs  to  be 
redrawn.  It  m^ay  be  a  part 
exposad  by  moving  or  dosing 
onottier  window,  or  it  may  be  a 
new  part  of  ttie  data  or aa 
exposed  during  scrolling. 


When  a  window  is  drawn  or  redrawn,  the  window  frame  is  drawn 
first,  followed  by  the  window  conlents.  The  Window  Manager 
handles  all  frame  drawing. 

When  a  window's  contents  need  to  be  redrawn,  the  Window 
Manager  generates  an  update  event  that  includes  a  pointer  to  the 
affected  window  in  the  message  field  of  the  event  record.  Your 
application  should  respond  to  update  events  as  follows: 

1.  Call  BeginUpdate.  This  procedure  temporarily  replaces  the 
visible  region  of  the  window's  GrafPort  with  the  intersection  of 
the  visible  region  and  the  update  region.  It  then  dears  (resets 
to  zero  size)  the  update  region  for  that  window. 

2.  Draw  the  window  contents.  Because  of  step  1 ,  the  redrawing  is 
automatically  clipped,  or  limited,  to  the  part  of  the  visible 
region  that  needs  updating. 

3.  Call  EndUpdate  to  restore  the  actual  visible  region. 

•t*  Tasf^asier:  If  you  use  TaskMaster,  diis  procedure  is  done  for 
you,  as  long  as  you  provide  Ta-skMaster  with  a  routine  that 
draws  your  window's  contents  (equivalent  to  step  2,  above). 
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*>  llodgePodge:  Although  it  uses  TaskiMaster  and  doesn't  really  1 
need  an  update  routine,  HodgePodge  has  a  short  example  ofj 
an  update  routine  in  the  code  that  creates  one  of  its  dialog  ■ 
boxes.  Sec  the  listing  of  ShowPleaseWait,  under 
"Constructing  Dialogs  and  Alerts,"  later  in  this  chapter, 

Moking  a  window  octive 

A  number  of  Window  Manager  routines  change  the  state  of  a 
window  from  inactive  to  active  or  from  active  to  inactive.  For 
each  such  change,  the  Window  Manager  generates  an  activate 
event.  When  the  Event  Manager  finds  out  from  the  Window 
Manager  that  an  activate  event  has  been  generated,  it  passes  the 
event  on  to  Ihe  application  through  GetNexlEvent. 

Activate  events  for  dialog  and  alert  windows  are  handled  by  the 
Dialog  Manager,  so  your  application  doesn't  have  to  bother  wi 
them,  In  response  to  activate  events  for  windows  created  direct! 
by  your  application,  you  might  take  actions  such  as  the  follo^ 

□  Inactivate  controls  in  inactive  windows,  and  activate  controls 
active  windows. 

□  In  a  window  that  contains  text  being  edited,  remove  the 
highlighting  or  blinking  cursor  from  the  text  when  the  wind 
becomes  inactive,  and  restore  it  when  the  window  becomes 
active. 

□  Enable  or  disable  a  menu  or  certain  menu  items  as  appropria 
to  match  what  the  user  can  do  when  windows  become  active 

inactive. 

❖  TaskMasttr.  If  you  use  TaskMaster,  highlighting  of  standard 
windows  and  controls  is  handled  for  you.  Enabling  and 
disabling  of  menu  items  is  not, 

<•  Hodgepodge:  To  keep  menu  highlighting  in  agreement  with 
activate  events,  HodgePodge  calls  its  subroutine  CheckFront 
each  time  through  the  event  loop. 
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Local  coordinates  are  discussed 
mtier  "Drowing  to  the  Screen'  in 
Chapter  3. 


Vour  application  determines  hiow 
mony  pixels  are  needed  to  stilft 
ttiB  Image,  See  'Putting  Controls 
Ir  Windows.'  later  In  ttils  chapter, 


Scrolling 

Scrolling  is  the  process  by  which  the  user  can  bring  diFfcrent  parls 
of  3l  document  (daca.  area)  into  view  in  a  window.  To  accomplish 
scrolling,  the  user  manipuIaEes  scroll  bars,  standard  window 
controls  managed  by  the  Control  Manager.  An  application  Cor 
TaskAlaster)  responds  to  user  manipulation  of  scroll  bars  by; 

1,  Updating  the  appearance  of  the  scroll  bars  to  reflect  the 
change  in  position  of  the  daca  area.  This  step  is  described 
under  "Putting  Contrcils  in  Windows,"  later  in  this  chapter. 

2  Showing  a  new  part  of  the  document  in  the  window.  The 
application  (or  TaskM aster)  does  this  by  shifting  the  image  in 
the  window,  then  changing  the  window's  heal  coordinates  and 
redrawing  the  parts  of  the  data  area  brought  into  view.  This  step 
is  described  below. 

TaskMaster:  If  your  application  uses  TaskMasier,  it  can  have 
TaskMaster-controlled  scroll  bars  (frame  scroll  bars)  in  iis 
windows.  In  that  case  the  application  need  have  no  scrolling 
routines  at  all.  The  following  applies  only  if  your  application 
creates  and  manipulates  its  own  scroll  brars. 

*  Hodgepodge:  Because  ii  calls  TaskMaster,  Hodgepodge  has  no 
scrolling  procedure. 

Consider  a  pixel  image,  part  of  wtiich  is  displayed  in  a  window, 
such  as  the  dollar  bill  in  Figures  3-5  and  3-6.  Let's  say  that  the 
window  presently  shows  George  Washington's  face  (Figure  4-4), 
and  the  user  wants  to  scroll  the  image  to  bring  into  view  the 
circular  Federal  Reserve  seal  to  the  left  of  Washington.  With  the 
mouse,  the  user  activates  the  left-facing  arrow  on  the  bottom 
scroll  bar.  When  your  application  determines  that  there  has  been 
a  mouse-down  event  in  that  part  of  the  scroll  bar,  it  should 
respond  as  follows; 

1.  Call  the  QuickDraw  routine  ScroILRect  and  tell  it  to  move  all 
the  pixels  in  the  content  area  of  the  window  a  certain  number 
of  pixels  to  the  right,  George  shifts  a  bit  to  the  right.  The  way 
ScrollRect  works,  any  pixels  moved  off  the  right  edge  of  the 
window  are  lost,  and  extra  pixels  added  to  the  left  edge  of  the 
image  are  blank  (colored  with  the  background  pattern). 

2.  Your  onscreen  image  has  been  shifted,  but  QuickDraw  hasn't 
automatically  filled  in  the  new  part  of  the  image  that  has  come 
into  view.  However,  SaoUEect  returns  information  to  you  that 
tells  you  exacdy  what  part  of  your  window  needs  redrawing.  Call 
InvalRgn  to  add  that  newly  exposed  area  to  the  window's 
update  region. 
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See  the  toolbOK  reference  for 
instructions  on  Installing  □  control 
action  procedure. 


3.  Call  BeginUpdate, 

4  Call  your  routine  that  draws  window  contents.  What  that  roulinll 
should  do  is: 

a.  Set  the  iocaJ  origin  to  its  scrolled  value:  what  it  was  the  last 
time  the  window's  contents  were  drawn  PLUS  the  (negauVe 
value  of  the)  number  of  pixels  that  ScrollRect  shifted  the 
image. 

b.  Draw  the  window's  contents  (perhaps  by  calling  PPToPort), 
The  image  is  properly  shifted  and  clipped  so  that  just  the 
needed  part  is  drawn,  There's  the  seal! 

c  Set  the  local  origin  back  to  (0,0). 

5.  Call  EndUpdate. 

If  you  put  the  above  steps  into  a  control  action  procedure,  they 
will  be  called  repeatedly  as  long  as  the  user  holds  the  mouse 
button  down  with  the  pointer  in  the  scroll  bar.  The  image  will 
scroll  continuously. 

Alternatively,  if  conlinuom  scrolling  is  unnecessary,  you  can 
ignore  steps  3  through  5.  The  InvalRgn  call  causes  the  Window 
Manager  to  generate  an  update  event  for  exactly  that  part  of  the 
window,  and  the  next  time  through  the  event  loop,  your  regular 
update  routine  redraws  the  window.  The  redrawing  won't  happen, 
though,  until  the  user  releases  the  mouse  button. 
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a.  Part  of  a  document  displayed 
in  □  GrafPart 


b.  Application  scrolls  Image  to 
the  right.  Pixefs  moving  off  right 
edge  ore  lost;  new  area  filled 
with  bockgrouhd  pixels, 


 i»mi  iMMflw  fum  mam  u  ^ 

im  UPOTED  STATES  OF  AMERIC 


c.  Applicciticr  i^pdi-ites  fhe  -lew 
□reo  scrolled  into  view  by  shifting 
cooidlnates  and  redrawing. 


Figure  A-A 

Scfolling  Q  pixel  image  In  a  window 


Important  When  a  window  is  c  reated ,  tho  Wind  ow  Monagar  assigns  Its  port 
rectangle  origin  a  value  of  C0,0)  In  !ocal  coordinates.  Whenever  It 
redraws  the  window  frame,  the  Window  Manager  requires  the  orl 
to  have  that  some  value. 

Therefore^  every  time  you  draw  your  window's  contents  you  shouldt^ 
<1)  set  the  origin  to  whatever  Is  appropriate,  (2)  drow  the  contents, 
and  then  (3)  restore  ttie  origin  to  (pjO), 


Ihe  sequence  of  subroutine  call 
described  In  thte  section  Is 
diagrammed  in  Apparidix  D. 


DoOpenlfem  Is  In  ttie  source  file 
MENU.PAS. 


Opening  a  window:  an  exampie 

Ttie  following  example  from  HodgePodge  shows  the  steps 
involved  in  allocating  the  memory  for,  creating,  and  drawing  the 
initial  contenis  of  a  window.  Remembier  ihat  in  HodgePodge  the 
are  two  types  of  window:  one  type  displays  picture  files  and  Lhe 
Other  displays  lines  of  text  using  a  particular  font. 

The  sequence  Starrs  when  the  user  chooses  Open  from  the  File 
menu  or  Show  Font  from  the  Font  menu.  In  either  case  execution 
passes  from  DoMenu  to  the  routine  DoOpenltem.  DoOpenltesiis 
very  short: 


procedure  DoOpenltem/ 


(begin  DoOpenltem...) 


if  windex  <  lastWind  tJien 
if  OpenWindow  than 

AddtoManu 
else 

sise 

ManyWindDxalog; 


{If  there's  toom  for  another  winciow,„) 
{call  OpenWindow.  If  it  opens  0K_.} 
{...add  its  name  to  the  Windows  menu} 

(If  16  windows  already  open...} 

(put  up  a  dialog  and  disallow  open) 

{End  of  DoOpenltem) 


Note  that  DoOpenltem  calls  both  OpenWindow  (to  open  the 
window)  and  AddToMenu  (to  add  the  window's  name  to  the 
Windows  menu),  AddToMenu  is  described  under  "Maldng  and 
Modifying  Menus"  in  Chapter  5.  If  16  windows  are  already  open, 
HodgePodge  dees  not  allow  another  to  be  opened. 
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WINDOW.PAS, 

i 


Open  Window  determines  which  type  of  window  is  to  be  opened, 
and  prompts  the  user  for  the  necessary  information  (picture 
filename  or  font  characteristics).  It  then  calls  the  routine 
DoTheOpen^  which  actually  opens  ihe  window,  OpenWindow  looks 
like  this: 


iunction    OpenWindow:  Boolean ; 


begin 

OpenWindow  FALSE; 

if  (IioWord  (Event .  wrtTagkOata  -Fontltero)  then 

B         if  DoChooseFont.  then 
■  if  DoTheOpen  then 

P  OpenWindow  TRUE 

find 
else 

if  AakUaer  then 

if  DoThaOp€tn  than 
OpenWindow  TRUE 

and; 


(be^in  OpenWindow...} 


(initial  value  of  function  ■  FALSE! 
(if  it  ia  a  font  window,..} 

(...and  if  the  user  doesn ' t  cancel,,,} 
{...and  if  the  window  opena  OK...} 
(OpenWindow  con^ietes  succesafully) 

{if  it  ia  a  picture  window...) 

{..And  if  the  user  doesn't  cancel... 1 
(..And  if  the  window  opens  DK_.J 
(CpenWindOW  cosnpletes  successfully) 


{End  of  OpenWindow} 


DoTheOpen  is  In  ths  source  file 
WINDOW.PAS. 


The  compJete  form  at  for  the 
NewWlndow  parometei  lisf  is 
given  under  "Window  Manager' 
\r\  the  Apph  Toolbox 
Heferenca 


I 


DoChooseFont  was  described  eaflier  in  tliis  chapter,  AskUser  is 
described  in  Chapter  5,  under  "Communicating  With  Files  and 
Devices." 

Once  it  has  all  the  information  it  needs,  OpenWindow  calls 
DoTheOpen  to  open  the  window.  DoTheOpen  looks  like  a  long 
and  complex  routine,  bul  that's  partly  because  it  is  two  routines  in 
one;  it  handles  two  types  of  windows.  It  also  does  a  lot  of 
assignment  arid  initialisation  that  your  programs  may  not  need  at 
this  point.  Weil  break  its  description  into  chunks  to  make  it  easier 
to  follow, 

DoThsOpen  starts  by  allocating  memory  for  the  window  data 
record  (a  structure  defined  by  HodgePodge),  and  putting  some 
initial  values  into  the  i\'ewWmdow  parameter  list,  a  toolbox- 
defined  structure  that  is  a  required  input  to  the  NewWindow  call. 


otio/i  DoTheOpen  ;  Boolean; 


vai       theWindow      :  GrafPortPtr; 
myEJataHandls:  WindOataH; 


theMenuStr     :  Str253; 
ourFontlnfo  ;  FontlnfoRec,' 


(begin  DoTheOpen...} 

(a  pointer  to  our  window) 
(a  handle  to  ouz  own  window-data 
record — defined  in  GLOHALS.PAS} 
(window's  title  for  menu  display) 
(to  hold  font  infornation} 


Cf  eatlrig  wirxiow/s  1 2 1 


DoTheOpen 


FALSE; 


myDatafiandle  : -  WindDataH { 

HBwHflJtvdla  taiaeof  (MindDataRec)  , 
myMerrenrylD, 
att  r  Locked+att  tF  ijted, 
Ptr  (0)  ) ) : 
if  isToolError  then 
Exit; 


with  inyWind  do 

pacaraLength 

wFrameBits 

wRefCon 


:  -  Jjizeof  (ParamLiat)  ; 
SDDAO; 

Longint (nyUataHandlfe) ; 


SatRsct  (wZooiti,  0,26,  520,  190) 


wCoJor 
wYOrigin 
wXOrigin 
wDataH 
wDataW 
wMascH 
wMaxW 
wScrollVer 
wScrollHor 
wPacfeV&r 
wPageHor 
WlnfoRefCon 
wInfoHeight 
wframaOefProc 
wlnfoDefProc 
wPlane 
wStorage 
end,- 


NIL; 

0; 

0; 
18a 

£40 

200 

€40 

4; 

16; 

40; 

160; 

0; 

0; 

NIL; 
NIL; 

-1; 
NIL; 


(initial  value  of  function  -  FALSE} 

{get  a  handle  to  our  record  by...} 
{..requesting  memory  with  these...} 
{attribytes:     size,  User  ID,} 
{loclced  and  fixed,} 
{ anywhere ] 

(terminate  if  menrory  unavailable) 

(myWind  is  a  window  parameter  block,] 

(...recjuired  input  to  HawWindow  call) 

{Initialige  the  window's  features:} 

{total  size  of  list} 

{this  specifies  scroll  bars,  etc} 

(handle  to  our  window  data  record} 

{window  size  £  post ion  when  zoomed) 

{no  Colors  for  this  window) 

(y-coord.  of  port  rect  origin) 

(jc-coord.  of  port  ract  origin} 

( document  height } 

(document  width) 

(max,  window  height  ta  grow) 

(max.  window  width  to  grow) 

{amt.  to  scroll  if  V.  arrow  clicked) 

{an*,  to  scroll  if  h.  arrow  clicked) 

{amt.  to  scroll  if  v.  page  clicked} 

{amt.  to  scroll  if  h.  page  clicked} 

(no  info,  bar  for  this  window) 

(no  info  bar  for  this  window) 

(no  special  f rame-drawimj  routine} 

(no  special  info-bar  content  routine) 

(malce  this  window  fcontmost} 

(let  Window  Mgr  allocate  the  memory) 


theMenuStr 


concat {'-■', 

myPeply , filename, 
'  \N', 

IntToString ( 

FirstWindltein+wIndejc)  , 
' \0 .  ' )  ; 


with  myDataHandle"*  do 

najne  :  -  ntyHeply .  f  i  laname ; 
i»nuStr  theMenuStr; 
menu ID  FirstWindltem+wIndex? 
end/ 


(Make  a  title  for  the...) 
i  ...window  to  appear  in_.} 

{...theWindows  menu.} 

(In  the  window-data  record,..} 

(-Jill  in  the  name  field) 
{...fill  in  the  menu  title  field} 
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After  this  iniiial  altocaiion,  DoTheOpen  sets  up  Ihe  window  to 
display  either  text  or  a  picture,  tl  inserts  into  the  KewWindow 
parameter  list  a  pointer  to  the  procedure  thai  draws  the  window's 
interior,  and  sets  the  remaining  fields  in  the  window-data  record. 


if  I*Word (Event. wraTaakData)    -  Fontltem  thsn 

myWind.wContDefProc  :.-  @ DispFont Window; 
with  myDataHandle""  do 
begin 
tlag       :-  1; 
theFont  :~  DesiredFont; 
isMono     :=  isMonoFont; 
end; 

IrtBtallFont  (desiredFont.,  0)  ; 
Gatfontlfifo (ourFontlnf o) ; 
ntyWind . wDataH        15*  (ourFontrnf o-ascent+ 
ourFont Info .descent) : 

end 
alse 

myWind.wContDefProc  :-  gPaint; 
with  inyDataHandle*"  do 
begiii 

flag  0; 

pict  picHndl; 


end; 


I  if  it  is  d  font  window...) 
{DispFont Window  will  dtaw  contents) 


11  tneana  it's  a  font  window} 
(store  present  font  ID  in  thsFont } 
(store  present  setting  of  isMonoFont) 

(lesad  the  desired  font  into  memory  J 
{...get  its  characteristics..,) 
(...and  calculate  dacuinent  height — ) 
(1.5  =  2  +  no.  of  lines  in  documentl 
(end  of  IF  it 'a  a  font  window) 

{But  if  it's  a  picture  window.,,) 

(Paint  will  draw  contents} 


(0  meana  it's  a  picture  window) 
(store  handle  to  desired  picture...} 
{„,  [detennined  by  AakUser)  ) 
{end  of  IF  it's  a  picture  window) 


Now  DoTheOpen  determines  where  on  the  screen  the  window  is  to 
appear.  Each  newly-opened  window  is  ofTset  down  and  to  the  right 
from  the  previously  opened  window.  Recall  from  SetUpWindows 
(Chapter  2)  that  ISizPos  is  the  initial  position  and  size  of  a 
window. 


tfith  itiyMind  do 
bmgin 

wTitle  SmyData Handle 
SetRact (^Position, 
wXoffaet  + 
wYoffset  + 
wXoffsat  + 
wYoffset  + 

end; 


.name; 


iSizPoa.hl, 
iSizPos-vl, 
iSizPoa.hS, 
iSizPoa.v2) ; 


wXoffaet  :-  wXoffset  +  20; 
wYoffset       wYoffaet  +  12; 
if  wYoffset  >  120  thsn 
wYoffset  :=  12; 


(In  the  window-data  recordL.) 

(set  window  title  to  naine  field) 

(Add  the  window  dimensions  to  then.) 
(...current  X-  and  Y-  offsets} 

{end  of  setting  record  fields] 

(Then  increment  offsets-.) 

(...to  set  position  of  next  window) 

1 (after  10  windows  make  another  raw) } 
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Fmally,  now  that  everyLhing  is  all  set  up,  DoTheOpen  creates 
window  .isGir.  It  uses  ihe  NewWindow  call,  passing  to  NcwW 
the  parameter  list  that  DoTheOpen  just  filled  in.  You  can  see 
Lhe  fol  owmg  code  that  opening  a  window  is  quite  simple  and 
snort,  It  IS  the  preparation  and  initialization  that  makes  the 
routine  seem  long  and  complicated. 


Qd,- 


SiitFort  (theWindow)  ; 
DoTheOpen  ;■=  TRUE; 


{Opcm  the  window— NewWindow 
retuma  a  pointer  to  it) 
(Mafte  the  window  the  active  port) 
(Adjust  window  origins  to  make 
di the ted  color a  come  out  right} 
(Go  back  to  the  arrow  cuesox} 
(DoTheOpen  coinpletea  successfully! 
iEnd  of  DoTheOpen} 


Putting  controls  in  windows 

A  control  is  an  ob/ect  on  the  IICS  screen  with  which  the  user 
using  the  mouse,  can  cause  instant  action  wiLh  graphic  result^ 
^hange  settings  to  modify  a  future  action.  Controls  are 
fundamental  tc  the  concepts  behind  the  Human  Interface 
Gmddmesi  they  provide  a  simple,  intuitive  interface,  permitting 
the  user  to  affect  the  course  of  an  application.  If  weil^JSigiT^ 

they  reinforce  the  feelings  of  user  control,  friendliness  and 
consistency  that  mark  a  good  desktop  application. 

helps  you  create  and  manipulate  controls.  The  Control  Manager 

zt::-''-'         -  -  ^-^^ 

Controls  may  be  of  various  types,  each  with  its  own  characteristi 
appearance  on  the  screen  and  responses  to  the  mouse.  Eac^ 

lottT  propcrties^such  ast  , 

bcation,  si.^,  and  setting-bu,  controls  of  the  same  type  behaJ 
m  the  same  general  way.  ocDave| 


Types  of  controls  ~   

Ccnain  standard  types  of  controls  are  predefined  for  you  Vour 
Sons  ^^^'^^n^^d  ^^ntrols  perform  a  number  of 
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■  Buttons  cause  an  irnmediaie  or  continuous  action  when  clicked 
or  pressed  with  ihe  mouse.  They  typically  appear  on  the  screen 
as  rounded-comer  rectangles  with  a  liile  centered  inside. 

■  Check  boxes  retain  and  display  a  setting,  either  checked  (on) 
or  unchecked  (ofl);  clicking  with  the  mouse  reverses  the  setting. 
On  the  screen,  a  check  box  appears  as  a  small  square  with  a 
title  to  the  right  of  ii;  the  box  ii  either  filled  in  with  an  X 
(checked)  or  empiy  (unchecked).  Check  boxes  are  frequently 
used  to  conuol  or  modify  some  future  action,  instead  of 
causing  an  immediate  action  of  their  own.  More  than  one  box 
may  be  checked  at  any  one  lime. 

■  Radio  buttons  also  retain  and  display  an  on-or-off  setting, 
They're  organized  into  families;  only  one  button  in  a  family 
should  be  on  at  a  time.  Clicking  any  button  on  should  mm  off 
all  the  others  in  the  family,  like  the  buttons  on  a  car  radio.  The 
radio  buuon  that's  on  is  filled  with  a  small  black  circle. 

B  Dials  display  a  quantitative  setting  or  value,  typically  in  some 
pseudo-analog  form  such  as  the  position  of  a  sliding  switch,  the 
reading  on  a  thermometer  scale,  or  the  angle  of  a  needle  on  a 
gauge.  The  setting  may  be  displayed  numerically  as  well. 
The  control's  moving  part  that  displays  the  cuffent  setting  is 
called  the  indicator.  The  user  may  be  able  to  change  a  dial's 
setting  by  dragging  its  indicator  with  the  moose,  or  the  dial 
may  simply  display  a  value  not  under  the  user's  direct  control 
(such  as  the  amount  of  free  space  remaining  on  a  disk). 

The  standard  controls  and  a  few  other  typical  controls  are 
illustrated  in  Figure  4-5. 

Button  1 


Button  2 


E  Check  box  1 
H  Check  box  Z 
□  Check  box  3 

O  Radio  buttoi)  1 
•  Rodio  button  2 
O  Radio  button  3 

Figure  4-5 

Standard  and  typical  controls 
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Scroll  bars 


Scroll  bars  are  predefined  dials.  Selecting  the  arrows  In  a  saoU 
bar  scrolls  data  a  line  at  a  time  Cor  an  analogous  number  of  pisdi 
in  the  horizontal  direction);  selecting  the  paging  regions  scrolli 
data  a  page  al  a  time;  and  dragging  the  thumb  to  any  position 
within  the  scrolling  area  locates  the  window  equivalenily  within 
the  data  area.  Although  each  of  these  components  may  seem  to 
behave  like  individual  controls,  they  are  all  parts  of  a  single 
control,  the  scroll-bar  type  of  dial.  You  can  define  other  dials  of 
any  shape  or  complexity  if  your  application  needs  them. 

❖  Note:  For  scrolling,  what  constitutes  a  page  and  what  constitutes 
a  line  are  definable  by  your  application. 

Figure  4-6  shows  the  parts  of  the  vertical  and  horizontal  saoU  bits. 


Up  arrow  - 


Page-up  region  - 
Thumb  — 


Page-down  region 


Down  arrow  — [5; 


Figure  i-6 

Parts  of  the  scroll  bars 

Scroll  bars  are  proportional— that  is,  they  show  the  relationship 
between  the  total  amount  of  data  and  the  amount  viewed  (and 
where  the  view  is  in  the  data).  As  Figure  4-7  shows,  the  thumb  is 
the  same  ratio  to  the  scrolling  area  (the  total  distance  between ! 
arrows)  as  the  content  region  is  to  the  data  area. 
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When  ihe  user  clicks  in  a  scroll  bar,  the  Conirol  Manager  returns 
lo  yuur  application  a  pan  code,  telling  it  what  part  of  the  scroll 
bar  the  event  occurred  in.  Depending  on  whether  it  is  in  an  arrow, 
paging  region,  or  thumb,  your  application  probably  should  scroll 
the  document  by  a  different  amount.  Once  you  know  how  much 
the  view  should  be  scrolled,  you  can  recalculate  the  scroll  bar 
values  to  keep  the  proportions  as  illustrated  in  Figure  4-7.  Then, 
call  SetCdValue  to  redraw  the  scroll  bar  with  the  thumb  in  the 
proper  new  position. 

❖  Note:  Part  codes  are  returned  for  all  types  of  controls,  but  they 
are  most  significant  for  complex  controls  such  as  scroll  bars. 

With  the  SctCtlParams  call,  you  can  store  in  a  scroll  bar's  record 
the  current  siiies  of  your  document's  data  area  and  content  region 
(window  size).  Then  you  can  easily  calculate  their  proportions  for 
setting  scroll  bar  values  after  scrolling  or  resizing. 


Figure  4-7 

Relation  of  scroll  bars  to  data  area 
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Hjgfillghting  can  m&an  dlffere-nf 
things  in  different  instances  but  ir 
Often  consists  of  Inverting  on 
object^ that  Is,  changing  aJi  its 
black  pJxete  to  whfte,  and  vfce 
versa  , 


Active  controls  and  highlighting 

cnlllirrh  P'^^^^'^^  '"^"^^  ^'l^n  the  cursor  is  over  a 

2       •  ^f,"^"^™'  ^  "^"^lly  tJghlJghied;  see  Figure  4-8,  If. 

JZT  fl  '  '"'^'^"^      ^  highlighted:  for  - 

example,  ,f  the  user  presses  the  mouse  button  when  the  point  J 
ms.de  .n  arrow  m  .  scroll  bar.  the  arrow,  not  the  whole  scroll : 
becomes  highlighted 

A  control  m.y  be  active  or  Inactive.  Active  controls  respond  tc 
Hie  users  mouse  actions;  inactive  controls  don't.  A  control  she 
be  made  mactive  when  it  has  no  meaning  or  effect  in  the  cur« 
sTSh  T  '^'"^^  ^'^^"^  "°  has  been  , 

scroll  to.  An  mactive  control  is  shown  in  some  special  way 
depending  on  its  control  type.  Figure  4-S  illustrates  some  a'ctive 
and  maciive  controls. 


^  Check  box 
Ci^  Radio  button 


rn — wg^ 


Button 


□  Check  box 
O  Radio  button 

ME 


Active 


Actrve  (high  lighted) 
Figure  4>3 

Active  conttols  and  Inactive  controls 


□  Check  bo!! 
O  Rodio  buttttflj 


Inactive 


TTie  title  and  outline  of  a  button,  check  box,  or  radio  button  are 
dimmed  automatically  when  the  control  is  made  inac've  H^Te 
4-8^shows  two  ddferenc  appearances  that  .n  inactive  scroll  bTr  L 

Tnv   K,   T  ^  ^'^'^^^^l  '"^ac^^e  b>^  making  it 

rt''bi^:?erd:^  ^^^^^^'^ 
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Using  controls 


Controls  and  windows 

Every  control  belongs  lo  a  window:  when  the  control  is  displayed, 
it  appears  within  that  window's  content  region;  when  manipulated 
wi[h  the  mouse,  it  acts  on  that  window.  All  coordinates  pertaining 
to  the  conuol  (such  as  those  describing  its  location)  are  given  in 
the  window's  local  coordinate  system.  Even  the  state  of  the 
control  can  be  tied  to  the  state  of  the  window.  A  bit  in  the 
window's  record  can  be  set  so  the  controls  in  the  window  will  be 
considered  inactive  if  the  the  window  is  inactive.  See  "Window 
Manager"  in  the  Apple  IIGS  Toolbox  Reference. 

<•  Frame  scroll  bars:  Frame  scroll  bars  (manipulated  by 

TaskMastcr)  work  the  same  as  other  controls,  but  are  part  of  a 
window's  frame  region  rather  than  its  content  region. 

Controls  and  events 

when  GetNextEvent  reports  thai  an  update  event  has  occurred  for  a 
window,  your  application  should  call  DrawControls  to  redraw  the 
window's  controls  as  part  of  the  process  of  updating  the  window. 

TaskMasier.  If  you're  using  TaskMaster,  you  needn't  redraw 
controls  that  are  part  of  the  window  frame — ^TaskM aster  takes 
care  of  it  for  you. 

When  GetNextEvent  reports  a  mouse -down  event  for  a  window 
that  contains  controls,  do  this: 

1.  Call  FindWindow  to  determine  which  part  of  which  window  the 
cui^or  was  in  when  the  user  pressed  the  mouse  button.  If  it  was 
in  the  content  region  of  the  active  window,  continue  with  step  2. 

2.  Call  FindControl  to  fmd  out  where  the  event  occurred. 

3.  If  FindControl  indicates  that  the  event  occurred  in  an  active 
control,  call  TrackConlrol  to  handle  user  interaction  with  the 
control,  TrackControl  handles  the  highlighting  of  the  control 
and  determines  whether  the  mouse  is  still  in  the  control  when 
the  mouse  button  is  released.  The  routine  also  handles  the 
dragging  of  the  thumb  in  "a  scroll  bar  and  responds  to  presses 
or  clicks  in  the  other  parts  of  a  scroll  bar. 
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4.  If  TrackControl  confirma  that  a  valid  control  was  selected,  do 
whatever  is  appropriate  as  a  response.  Of  no  control  was 
selected,  then  of  course  no  action  is  necessary). 

The  application's  exact  response  to  mouse  activity  in  a  control 
that  retains  a  setting  depends  upon  the  current  setting  of  the 
control.  For  example,  when  a  check  box  or  radio  button  is  die 
you'll  make  a  Control  Manager  call  to  change  the  setting  and 
draw  or  dear  the  mark  inside  the  control. 

*  TaskMaster:  If  your  applicaUon  calls  TaskMaster.  the  above 
procedure  is  handled  automatically  for  frame  scroll  bars  in 
standard  windows,  Only  if  you  have  other  controls  will  you 
need  a  control-drawing  routine. 

*  Hodgepodge:  Because  it  uses  only  window-frame  controls,  anJ 
because  it  calls  TsskMaster,  HodgePodge  has  no  specific  " 
routine  to  manipulate  or  draw  controls. 

Defining  your  own  controls 

In  addition  to  predefined  controls,  you  can  also  define  your  ou, 
custom  controls.  Perhaps  you  need  a  three-way  selector  switch,  i\ 
memory-space  indicator  that  looks  like  a  thermometer,  a  thrusteJ 
control  for  a  spacecraft  simulator,  or  some  other  special  type  of] 
control.  Controls  and  Iheir  indicators  may  occupy  regions  of  anJ 
shape. 

To  define  your  own  type  of  control,  you  place  a  control  definitlo 
procedure  in  your  application.  The  Control  Manager  stores  the 
address  of  the  procedure  in  the  ctlProc  field  of  the  control  recc 
when  you  create  the  control  with  a  NewConlro!  routine.  Later, 
when  the  Control  Manager  needs  to  perform  a  type-dependent 
acUon  on  the  control,  it  calls  the  control  definJUon  procedure, 
See  the  Apple  IIGS  Toolbox  Reference  for  details. 


Manipulating  lists  of  selectable  items 

If  your  program  displays  a  list  of  available  fonts,  files,  telephone 
numbers,  icons,  or  other  items  in  a  window,  it  may  put  them  in 
hsls,  as  defined  by  the  Apple  IIGS  Toolbox.  A  list  is  a  vertical 
arrangement  of  similar  items  on  the  screen,  with  a  scroll  bar  to 
the  right.  Each  item  in  the  list  is  selectable,  meaning  it  can  be 
highlighted  individually,  with  a  mouse  dick  or  other  action. 
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The  List  Manager  is  the  Apple  DCS  tool  set  that  creates,  manipu- 
lates and  supports  lists.  It  relieves  you  (the  programmer)  of  much 
of  ihc  housekeeping  involved  with  building  and  maintaining 
compHcaEed  lists  of  items  the  user  may  select  from.  Lists  created 
by  the  List  Manager  are  custom  controls,  called  list  controls;  that's 
why  we  mention  the  List  Manager  here,  under  the  Control 
Manager. 

You  create  a  list  as  a  iist  record,  with  a  specific  format.  You  may 
u.se  the  List  Manager  to  sort  the  list,  if  desired,  and  then  to  create 
the  list  control.  Once  the  list  control  is  drawn  on  the  screen,  tlie 
user  can  select  individual  items  or  a  range  of  items  from  the  list. 
How  your  application  handles  those  selections  is,  of  course,  up  to 
you. 


Constructing  dialog  boxes  and  alerts 

Two  of  the  most  useful  and  versatile  means  of  commmunicating 
with  your  application's  user  are  provided  by  dialog  boxes  and 
alerts.  The  Dialog  Manager  provides  these  capabilities  in  a  way 
consistent  with  the  Apple  Human  Interface  Guidelines, 

The  Dialog  Manager  is  a  sophisticated  window-  and  control- 
manipulation  tool  set.  It  automatically  performs  many  functions 
your  application  would  otherwise  have  to  manage  explicitly 
through  Event  Manager,  QuickDraw  II,  Window  Manager,  LineEdit, 
and  Control  Manager  calls. 


What  are  dialog  boxes? 

Your  application  typically  puts  a  dialog  box  on  the  screen  when  it 
needs  more  information  from  the  user  in  order  to  carry  out  a 
command.  As  shown  in  Figure  4-9,  a  dialog  box  resembles  a  form 
on  which  the  u.ser  checks  boxes  and  fills  in  blanks, 


Constructing  diotog  boxes  and  alerts 
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Print  the  document  rrnnrai  1 
®81/2"xirpoper  ^^^^ 
O  8 1/2"  X 14"  pcper    f   OK  ] 

13  Stop  printmg  of  ter  each  pog« 

Title;    |  flnnuol  report 


Figure  4-9 

A  modal  dialog  box 

By  convention,  a  dialog  box  appears  slighUy  below  the  menubr 
somewhat  narrower  than  the  screen,  and  is  centered  between  ' 

foSowing  ^'^^^^  °^  '^"^  "  ""^^  '"l'  «f 

□  informative  or  Instaictional  text 

□  rectangles  in  which  text  may  be  enter^;d  CiniUally  bJank  or 
containing  default  text  that  can  be  edited) 

□  controls  of  any  kind 

□  graphics  (icons  or  QuickDraw  II  pictures) 

□  anything  else  your  application  wants 

The  user  provides  the  necessary  information  in  the  dialog  boj 
for  example  by  entering  text  or  clicking  a  check  box.  There's 
usually  a  button  labeled  OK  to  tell  the  applicaUon  ,o  accept  tJ^ 
jnforma..on  provided  and  perform  the  command,  and  a  bu.^ 
labeled  Cancel  to  cancel  the  command  a.  though  it  had  never 
been  g.vcn  (retracting  all  actions  since  its  invocation).  Some 
dialog  boxes  may  use  a  more  descripUve  word  than  OK-  for 
s.mpl.cuy.  wc'iJ  refer  to  the  button  as  the  OK  buUon.  There  ma^ 

each  in'.  ^^'^  f^^^"™ 

eacii  m  a  d liferent  way. 
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Modal  or  modeless 


Most  dialog  boxes  require  ihe  user  to  respond  before  doing 
anything  else.  Clicking  a  buUon  to  perform  or  cancel  the  command 
makes  Ihe  box  go  awayj  clicking  outside  the  dialog  box  only  causes  a 
beep  from  the  speaker.  This  lype  of  box  is  called  a  modal  dialog 
box  because  it  puts  ihe  user  in  the  state  (or  mode)  of  being  able  to 
work  only  itisidc  the  dialog  box.  Figure  4-9  is  an  example  of  how  a 
modal  dialog  box  might  look;  note  that  it  has  no  close  box. 

One  of  the  buttons  In  a  modal  dialog  box  may  be  boldly  outlined;  it 
is  called  the  OK  button  (whatever  text  it  may  contain).  Pressing  the 
Return  key  has  the  same  effect  as  clicking  the  OK  button;  it  should 
initiate  the  preferred  (or  safest)  action  in  the  current  situation.  If 
there's  no  boldly  outlined  button,  pressing  the  Return  key  has  no 
effect.  A  Cancel  button,  if  present,  doses  the  dialog  box  and  cancels 
the  effects  of  all  work  done  while  the  box  was  open. 

Other  dialog  boxes  do  not  require  the  user  to  respond  before 
doing  anything  else,  They  are  called  modeless  dialog  boxes.  The 
user  can  work  in  a  document  window  on  the  desktop  between 
clicking  buttons  in  a  modeless  dialog  box.  Modeless  dialog  boxes 
can  be  set  up  to  respond  to  the  standard  editing  commands  in 
the  Edit  menu.  Clicking  a  button  in  a.  modeless  dialog  box  does 
not  make  the  box  go  away;  it  stays  on  the  desktop  so  tliat  the  user 
can  perform  the  command  again. 

As  shown  in  Figure  4-10,  a  modeless  dialog  box  typically  looks  like 
a  document  window.  It  can  be  moved,  made  inactive  and  active 
again,  or  closed  like  any  document  window.  When  you're  finished 
with  the  command  and  want  the  box  to  go  away,  you  can  click  its 
close  box,  or  you  can  choose  Close  from  the  File  menu  if  the 
dialog  box  is  the  active  window. 


Oi 


Find  text; 


Change 
Guidelines 


lai 


Change  to:  Guidelines 


Change  next 


Change  All 


Figure  4-10 

A  mode  [ess  dialog  box 


CortstTucting  dialog  boxes  and  alerts 
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UpcJate  routlns^  ore  described 
under  'Creating  Windows.' 
©ortter  fn  this  chapfgt 

ShowPleaseWalt  and 
HictePlecjjeWait  ore  fn  the  source 
fiie  DIALOG.  PAS. 


Some  dialog  boxes  may  in  fact  require  no  response  at  all.  Fo 
example,  while  an  application  is  performing  a  tirae  consumir, 
process,  it  can  display  a  dialog  box  that  contains  only  a  mesijge 
telling  what  it's  doing;  then,  when  the  process  is  complete,  the 
applicaUon  can  simply  remove  the  dialog  box.  HodgePodge  dOj 
this  with  the  ShowPleaseWalt  and  HidePleaseWait  routiW 
called  up  during  tool  initialization.  ShowPleaseWalt  also  ' 
demonstrates  how  to  bring  up  a  dialog  box  and  show  it 
immediately,  without  even  waiting  for  an  update  event  to  trio; 
its  display.  It  does  this  by  having  its  own  little  update  routine: 


procedure  ShowPleaseWalt ; 

vai"        IT  :  Rect; 

origPort  :  GrafPortPtr; 
msciWljndPtr:  GrafPortPtr; 

origPort      ;=  GatPort; 
msgWindPtr  : = 

GatHswModalCHalog  (@PlaHtTeinp)  ; 
SatHsctfr,  70, 19,  S40,2OD)  ; 
HawDItAin  ( 

msgWindPti^,  1502,  r,  15, 

e 'Please  wait  while  we  sat  things  up. 

0,  0,  Pointer  <0) )  ; 
B»glntJpd«ta   (msgWindPtrJ  ; 
DrawDlalog      (msgWindPtr) ? 
EndDpclata       { ms  gWi  ndPt  r )  ; 
end,- 


(begin  ShowPleaseWalt...} 

(rectangle  to  display  dialog  in) 
(cDitnvan  variable  with  HidePleaseWaitj 
{corrimon  variable  with  HidePleaaeWaitl 


{Save  the  current  GrafPort} 
(Open  the  dialog,  with  the  t.errplatft„i 
{  ..created  in  InltGlobals} 
{J^efine  rectangle  diTOnsiona] 
(Create  an  item  for  the  dialog:} 
{...with  these  parameters...} 
(...displaying  this  string..} 
{.and  with  these  other  paramaters) 
{Treat  this  like  an  update..} 
[.jnanuallv  draw  the  dialog...} 
{...and  end  the  update -handling} 
(End  of  ShowPleaseWalt} 


procedure  HidePleaseWait; 
begin 

CloBoDialog  (msgWindPtr! 
SatPort  (orlgPort)  ; 

and; 


{begin  HidePleaaeWait,..) 


{Remove  dialog  from  the  screen) 
(Restore  the  original  GrafPort) 
{End  of  HidePleaseWait ) 
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Figure  4-11  shows  what  the  dialog  box  created  by 
ShowPleaseWait  looks  like.  It  is  a  message  dialog  box  because  it 
requires  no  response  from  the  user,  and  disappears  on  its  own 
when  no  longer  needed. 


Plsose  wait  while  we  set  things  up. 


Figure  4-11 

HodgePodg©  message  dialog  box 


IT  you  wont  to  wttte  o  cusfom  olert 
jound  proceduf©,  see 
■Miscellaneous  Tool  Set"  and 
"Sound  Tool  Set'  In  the  Apple  IIGS 
Toolbox  Reference. 


Alerts 

With  alerts,  your  applications  have  a  standardized  way  to  report 
errors  or  give  warnings.  An  alert  box  is  similar  to  a  modal  dialog 
box,  but  appears  only  when  something  has  gone  wrong  or  must  be 
brought  to  the  user's  attention.  The  alert  box  is  usually  placed 
slightly  farther  below  the  menu  bar  than  a  dialog  box.  To  help  the 
user  who  isn't  sure  how  to  proceed  when  an  alert  box  appears,  the 
preferred  button  to  use  in  the  current  situation  is  doubly  outlined 
so  that  it  stands  out  from  the  other  buttons  in  the  alert  box,  The 
outlined  button  is  the  alert  box's  default  button;  if  the  user  presses 
the  Return  key,  the  effect  is  the  same  as  clicking  this  button. 

There  are  three  standard  kinds  of  alerts — Stop,  Note,  and 
Caution— each  indicated  by  a  particular  icon  in  the  upper-left 
corner  of  the  alert  box.  Figure  4-12  illustrates  a  Stop  alert.  You  can 
put  anything  you  like  in  the  upper-left  corner  of  an  alert,  including 
blank  space. 

The  alert  mechanism  also  provides  another  type  of  signal:  sound 
from  the  speaker.  The  application  can  base  its  response  on  the 
number  of  consecutive  times  an  alert  occurs;  the  first  time,  it 
might  simply  beep,  and  thereafter  it  may  present  an  alert  box. 
The  sound  isn't  limited  to  a  single  beep  but  may  be  any  sequence 
of  tones,  and  may  occur  either  alone  or  along  with  an  alert  box. 
As  an  error  is  repeated,  there  can  also  be  a  change  in  which 
button  is  the  default  button  (perhaps  from  OK  to  Cancel).  You 
can  specify  different  responses  for  up  to  four  occurrences  (.stages) 
of  the  same  alert. 
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Hodgepodge's  main  error  handler,  CheckDiakErrorisan 
example  of  a  routine  lhat  puts  up  a  Stop  alert  (Figure  4-12)  Jh^i 
exact  message  displayed  depends  on  the  particular  error  that 
occurred  CheckDiskError  is  listed  and  described  under  "E 
Handling  ,n  Appendix  D.  Some  of  its  features  are  described 
under  "Iiem  Lists,"  later  in  this  section 


figure  4-12 

HodgePodge  Stop  alert 


Dialog  and  aierf  windows 


A  dialog  box  appears  in  a  dialog  window.  When  you  call  a  DialoJ 
Manager  routine  to  create  a  dialog,  you  supply  the  same  kind  of 
To^rTT  y^^  "^^^^  a  window  with  a  Window  Maru  J 

Z  T'      -        '^'I'^'Pulste  a  modeless  dialog  window  with  ^ 
Window  Manager  or  QuickDraw  routines,  just  like  any  oth.r  , 
w  ndow-^showmg  it  hiding  it,  moving  it,  or  changing  its  size  ind' 
plane,  for  exanple.  If  you  want  dipping  to  occur,  you  can  set  the 
dialog  box  GrafPort's  dipping  region  with  QuickDraw  calls  " 

^^x^nL'^'^'^r^'"  '"T  "^""'l  have  .hesan« 

The  D  ^u"^  manipuhi.ng  an  alert  window,  however. 

The  D  alog  Manager  chooses  the  window  definition  procedure  so 

all  alert  wmdows  have  a  standard  appearance  and  behavSr 
The  size  and  location  of  the  box  are  supplied  as  part  of  the 
definmon,  You  don't  specify  the  alert  window  s  plane  "  ally, 
come,  up  in  front  of  all  other  windows,  Because  an  aien  tax 
requires  the  user  to  respond  before  doing  anything  else  and  the 
response  makes  the  box  go  away,  tlie  application  aoesn't 
manipulate  the  alert  window. 
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Ham  ID'S  ars  dtscui^ed  in  tMs 
SBCtlon,  under  ■|1em  Lists,' 


Dialog  records 

To  create  a  dialog,  you  pass  information  to  the  Dialog  Manager, 
with  which  it  creates  a  dialog  record.  The  dialog  record  contains 
the  window  record  fof  the  dialog  window,  a,  handle  to  the  dialog's 
item  list,  and  some  additional  fielcU.  The  Dialog  Manager  creates 
the  dialog  window  by  calling  the  Window  Manager. 

The  Dialog  Manager  passes  to  your  application  a  pointer  to  the 
dialog  port,  which  you  use  thereafter  to  refer  lo  the  dialog  in 
Dialog  Manager  routines  or  even  in  Window  Manager  or 
QuickDraw  II  routines.  The  dialog  pointer  is  equivalent  to  the 
window  pointer  for  the  dialog  box.  It  is  not  a  pointer  to  the  dialog 
record  or  even  to  the  window  record.  It  is  a  pointer  to  the 
GrafPort  record  only. 

You  can  do  all  the  necessary  operations  on  a  dialog  without 
accessing  the  fields  of  the  dialog  record  directly.  To  get  or  change 
information  about  an  item  in  a  dialog,  you  pass  the  dialog  pointer 
and  the  item  ID  to  a  Dialog  Manager  routine.  You'll  rarely  access 
information  directly  through  the  handle  to  the  item. 


(fan  Item  Is  enabled,  the  Oiolog 
Manngei  notifies  ths  appllcalion 
whenever  thie  user  selecls  ine 
(tern. 


Items 

A  dialog  box  or  alert  is  a  window  with  items.  To  create  a  dialog 
box  or  an  alert,  the  Dialog  Manager  needs  to  know  what  items  the 
window  contains.  It  also  needs  to  know  the  following  information 
for  each  item; 

□  The  item        This  includes  not  only  whether  the  item  is  a 
standard  control,  editable  text,  or  other  type,  but  also  whether 
it  is  enabled. 

□  A  display  rectangle,  which  determines  the  location  of  the  item 
within  the  dialog  or  alert  box. 

□  An  item  ID  number  uniquely  idcntilying  the  item  in  the  dialog. 
All  .subsequent  Dialog  Manager  calls  referring  to  that  item  will 
need  its  ID  number. 

□  Other  information  specific  lo  certain  types  of  items,  such  as  the 
item's  title,  its  initial  value,  its  colors,  its  orientation,  and 
whether  it  is  visible  or  invisible. 
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rfacJio  button 
Check  box — 


User-defin©d  controf- 
Scroil  bar- 


Ussf-deflned  dialog  ftem 


Important 


Ifem  type 

^hl'rZTA  "I ""'"'"^  ^P^^^ ^'^'-S  boxes  ' 
con  f.n^^^^  --^of  thc^.  Uen.  type,  arc  specified! 
t^  cut-iinea  consEanLs  or  combmations  of  constants  See  -n\,inn 
Manage,-  ,„  ,te  App,a  U.s  Tool.o.  ^./^  J^  J^ 


Icon 


fofic  text 


Button 


Print  tht  document 


^iVrxU"  paper 
O  8 1/2"  K 14"  paper  [ 
Stop  printing  of  ter  etrclj  page 

SomoIeMemo^ 
Hijd'Qcuin^nt 
Calc.Sheet 
ftngiiRFtf  


to  print 


Title: 


finnuol  report 


Progress  of  printing 


Fjgure  d-13 

Dfalog  Itsm  types 

An  editable  icxt  item  Cpredeflned  constant  -  %  ■  ,  A 

example,  .f  y<,u  wa,.t  to  prevent  the  user  temporarily  from 
mampLilatmg  an  item,  you  can  disable  it. 


Iter.  .  unchanga^rn'S^  '  ^'""^^'^  ^  ^'^^-^1 


or  .im  lar  diJZZ:     ^"""''PP^'^^'"^^  "ccd.  to  display  a  number 
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Display  rectangle 


Hie  view  rectangle  and  other 
aspects  of  UneEdIt  ors  described 
under  'UneEdIt  Too!  Set'  In  ttie 
^pte  HQS  Toolbox  Referenca 


Each  item  in  the  item  list  is  displayed  within  its  display  rectangle: 

a  For  standard,  controls,  scroll  bars  and  user  controls,  the  display 
rectangle  becomes  the  control's  enclosing  rectangle. 

□  For  an  editable  text  item,  it  becomes  LineEdit's  view  rectangle. 
The  text  is  dipped  (not  drawn)  wherever  it  extends  beyond  the 
rectangle.  In  addition,  tlve  Dialog  Manager  uses  QuickDraw  II  to 
draw  a  bordering  rectangle  outside  the  display  rectangle. 

o  Static  text  items  are  displayed  in  generally  the  same  way  as 
editable  text  items,  except  that  a  rectangle  isn't  drawn  outside 
the  display  rectangle,  Also,  there  are  three  different  formats  for 
static  text, 

□  Icons  are  aligned  wiih  the  display  rectangle's  origin. 

<•  Note:  Clicking  anywhere  within  the  display  rectangle  is 

considered  a  click  in  that  item.  If  display  rectangles  overlap,  a 
click  in  the  overlapping  area  is  considered  a  click  in  whichever 
item  comes  first  in  the  item  list. 


Item  ID 

Each  item  in  an  item  list  is  identified  by  an  Item  ID,  a  unique 
number  within  the  list.  By  convention,  the  OK  button  in  an  alert's 
item  list  should  have  an  ID  of  1  and  the  Cancel  button  should 
have  an  ID  of  Z.  The  Dialog  Manager  provides  predefined 
constants  equal  to  the  item  ID  for  OK  and  Cancel,  as  follows: 

ok  =1 
cancel  =  2 

In  a  modal  dialog's  item  list,  the  item  whose  ID  is  1  is  assumed  to 
be  the  dialog's  default  button  (unless  specified  otherwise);  if  the 
user  presses  the  Return  key,  the  Dialog  Manager  normally  returns 
the  ID  of  [he  default  button,  just  as  when  that  item  is  actually 
clicked. 

To  conform  with  the  Apple  Human  Interface  Guidelines,  the 
Dialog  Manager  automatically  outlines  the  default  button  in  bold, 
unless  there  is  no  default  button  (that  is,  no  button  item  with  ID 
1). 

jVoic;  If  you  don't  want  a  default  button,  do  not  create  any  item 
with  an  ID  of  ] , 
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Example 


MakeATemplQt©  is  In  the  sojice 
file  DEALOG  PAS, 


MakeATemplate  is  a  routine  called  by  CheckDiskError 
(described  earlier  and  listed  in  Appendix  D)  in  order  to  fill  in  I 
dialog  record  and  the  item  list  for  the  HodgePodge  stop  alert 
shown  in  Figure  4-12.  MakeATemplate  describes  the  basic  alert  j 
box,  including  what  is  to  happen  at  each  stage,  and  defines  two 
ilems:  an  OK  button  for  the  user  to  click,  and  a  static  text  item  I 
contains  the  error  message. 


procedure  MdkeAT&mplate  {  TheTemplate: 

MertTempPtr; 
TheStr:  StiingPtr) ; 

var        cur  rent  Iteitil :  ItemTeirplate; 

eurirentltein2:  ItamTemplate; 

begin 

with  TheTemplate"  da 
begin 

SatRact   [atEoundsRect, 120,30,520,  80)  ; 


atAlertID 
atStagel 
atStageZ 
atStageS 
at  St age 4 
atlteml 
atltem2 
at Items 
end; 


1500; 

580; 

580; 

580; 

$80; 

S currentlteml ; 
d current I tem2; 
NIL; 


with  currentltemi  do 
begin 
itemID        :=  1; 

SatRaet  {itemRect, 320 , 25, 0, 0) ; 
itenYType    :  ■  ID; 
itemDescr        6 'OK' ; 
itemValue  :=  0; 
iteiTFlag     :-  0; 
itemColor  NIL; 
end; 

with  currentrtem2  do 
begin 
itemlD  2; 

SotRact    (ItemBect, 72, 11, 639, ; 
itemTVpe     :=  15  +  S8000; 
itemDescr  :-  Pointer   {TheStrJ ; 
itemValue  :=  0; 
itemFlag  0; 
itemColoi:  :=  NIL; 
end,- 
end; 


{begin  MakeATenplate-.} 
{toolbox -defined  structuire) 

{First  define  alert  box;) 
{bounding  rectangle  for  alect) 


{at  each  stage,  make  alert...) 

{..visible  but  silent} 

{ptr  to  first  item's  template! 
{ptt  to  2nd  item's  tenplate) 
{terminatea  item  list} 
{end  of  defining  box  ten^slate} 

{Now  define  item  1;} 

{item  #1  =  default  item] 
{display  rectangle} 
{it's  a  buttton  item) 
{text  in  button) 
{initial  value  ■  0} 
{=default  style) 
{no  color) 
{end  of  item  1) 

{Now  define  item  2;) 


{display  rectangle} 

{disabled  static  text) 

(the  string  passed  to  this  routine) 

(no  initial  value) 

{default  style} 

(no  color) 

(end  of  item  2} 

(End  of  HakeATen^>late ) 
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Using  dialogs 

In  most  cases,  you  probably  won't  have  to  make  any  changes  to 
the  dialogs  from  the  way  they're  defined  at  their  creation. 
However,  (.here  are  calls  to  modify  items,  move  controls,  or 
change  text.  If  you  want  the  font  in  your  dialog  and  alert  windows 
to  be  somcihing  other  than  the  system  font,  call  SetDAl-'ont  to 
change  the  font. 

To  handle  events  in  a  modal  dialog,  call  the  routine  ModalDialog 
after  putting  up  the  dialog  box.  If  your  application  includes  any 
modeless  dialog  boxes,  they're  a  bit  more  complex  to  handle; 
part  of  your  event-handling  will  include  determining  whether 
events  need  to  be  handled  as  part  of  the  dialog  box.  You  can 
support  the  use  of  the  standard  cut,  copy,  paste,  and  delete  editing 
commands  in  a  modeless  dialog  box. 

You  can  substitute  text  in  static  text  items  with  text  diat  you  specify 
in  the  ParamText  routine.  This  means,  for  example,  that  a 
document  name  supplied  by  the  user  can  appear  in  an  error 
message, 


Ths  de$k  scrop  is  described 
under  "Supporting  Other  Desktop 
Featutes'  in  Chapter  5. 


Editing  text  witti  LineEdit 

To  provide  simple  text-editing  capabilities  needed  for  dialog 
boxes  and  other  general  purposes,  the  Apple  IIGS  Toolbox 
includes  the  LineEdit  Tool  Set.  The  routines  in  LineEdit  provide 
basic  text-editing  capabilities  that  follow  the  Apple  Human 
Interface  Guidelines,  These  capabilities  include 

□  inserting  new  text 

□  deleting  characters  that  are  backspaced  over 

□  translating  mouse  activity  or  arrow  keys  into  text  selection 

□  deleting  selected  text  and  possibly  inserting  it  elsewhere 

□  copying  selected  text  without  deleting  it 

LineEdit  uses  inverse  highlighting  to  show  the  current  text 
selection,  or  a  blinking  vertical  bar  to  show  the  insertion  point. 
LineEdit  places  cut  or  copied  text  into  the  LineEdit 
scrap — different  from  the  desk  scrap. 
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LineEdit  is  not  a  complete  text  editor,  rt  does  not  support 

°  T^t.T  ''^i^^^^^^-  P-  'in^  (except  when  using 
LETextBox  or  LETeJCtBox2) 

°  rS  T'  '^'^     '•^"^  both  the  left  and 

right  margins  (except  when  using  lETextBox2> 

a  automatic  word  wrap  (except  wher.  using  LETextBox2) 

□  scrolling 

□  fonts  that  kern  characters 

□  tabs 


Diafog  summary;  HoclgePodge7^;iS^iS::7ia 

■ailing  up  icmolaJ^.  °  '"        ™''^>         l-i"  t| 

^iiuwrxeasewait  (described  earlier). 

The  routine  starts  out  by  accessing  and  allocating  space  for  th^ 
Apple  icon  wc  want  to  display  in  die  bnx  i.Tw  ^  n 
button  for  the  user  to  rlirlr  ?l  n      ^  "^^""^^^ 

uie  user  to  chck.  Fmally.  n  draws  the  text  items  in  the 
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procedure  DoAboutIt«m; 


{h&jin  DoAboutltem...) 


var        aboutDlog  :  GrafPortPtr; 
r  :  Rect ; 

itemHit       :  Integer; 
applelconP:  Ptr; 
applelconH:  Handle; 

begin 

SstRact   (r, 146, 20, 493, 192 > ; 

aboutDlog  : =  tlawModalDialog (r, TRDE, 0} ; 

SotRact   (r, 270( 153, 0, 0)  ; 
KewDZtam(aboutDlogr  1<  r ,  Buttonlteni, 
e  'OK" ,  0,  0,NIL)  ; 


IpQinter  to  this  dialog} 

{item  selected  by  user) 

(pointer  and  handle  to  the  Apple„l 

l_J.con  created  in  InitGlobals) 


{"  rectangle  the  dialog  appears  in} 
{Open  the  dialog:  in  rectangle  r, 
visible,  no  reference  value} 
{Define  a  display  rectangle  and..) 
{-jTiajte  a  dialog  item  for  it:..) 
{„.the  OK  button) 


S«tR«ct    (r,20,  135, 0, 0) ; 

applelconP  SApplelcan; 

applelconH  iApplelconP," 

NAHDItam [aboutDlog,  3,  r, 

iconltertri-itemDisable, 
ApplelconH, 0, 0,NIL) ; 


StttPort  UboutDlog) 
S»tror*Color  (0); 
S  Btfla  cltColo  r  (15); 


Hodgepodge ' ) ; 


(Define  another  display  rectangle...) 
(..get  a  handle  to  the  Apple  icon,..) 

(make  it  a  disabled  icon  item} 

(For  the  rest  of  the  text,  simply 
Tfivxte  it  directly  in  the  port, 
rather  than  creating  dialog  items ) 

(make  sure  this  is  the  active  port] 
(foreground  color  =  black) 
(h«c)4ground  color  ■  white) 


Mov»To  (40,17); 
SatTAXtraca  (8)  ,■ 
Drawstring 

(' 

SatTaxtTaca   (0)  ; 
MoveTo  (40,27); 
DrairString 

( '  A  potpourri  of  routines  that ' ) ; 

MovftTo  (4  0,37); 
Drawstring 

( '  demonstrate  nmny  features  of • } ; 

MdvaTo  (4  0,4  7); 
Drawstring 

( '  the  Apple  IIGS  Tools . ' ) ; 

MovaTo  (40,67); 
DrawStxing 

('  By  the  Apple  IIGS  Development  Team"); 

MovaTo  (3G,77); 
DrawStxing 

("Translated  to  TML  Pascal  by  TML  Systems' J ; 


(move  the  pen  to  starting  position,.,) 
( (change  to  outline  text) ) 

(Draw  the  first  line...) 
( (go  back  to  plain  text) ) 
(Move  to  next  line  and  continue™} 
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MoveTo  {40,B7f; 
DrawString 

Drawstring 

Mavei^  (40,li7)T^''  "served-,; 
Drawstring 

itemHit  :°  ModaiDialog(NIL); 
CXoaeDialog(aboutOlog) ; 


end/ 


fcall  M«iaiDialog;  it  returns  when 
any  en.bl.d  iten.  is  s^l.ct.dj 
(Close  the  Dialog  when  OK  clicked) 

iEnd  of  DoAboutltem} 


fl  potpourri  of  routines  thot 
demonstrotemana  features  of 
the  Rpplf  JIGS  Tools. 

rrn!?in^l!!l'''r J^^^ DeveJopfflent  Team 
rranslated  to  THL  Posi;o]  b^ML  SustMs 

Coparigfit  Apple  Computer,  Inc. 

1986-87,  AM  rights  reserved 
i/'J.fl  23-Sep-e7 


ffgure  4-J4 

Ths  'About  Hodgepodge..."  dioiog  box 
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This  chapter  concludes  our  brief  discussion  of  the  Apple  IIGS 
Toolbox.  The  tool  sets  described  here  can  help  you  accompli 
these  tasks:  *^ 

D  creating  menus 

□  supporting  other  desktop  features  such  as  desk  accessori^ 
cut-and-paste 

accessing  external  devices  and  files 
generating  and  playing  sounds 
performing  mathematical  computations 
controlling  parts  of  the  Apple  JIGS  operating  environment' 


□ 

□ 
□ 
□ 


Making  and  modifying  menus 


Pull-down  menus  are  an  imporun:  part  of  the  desktop 
environment.  Menus  allow  users  to  examine  all  choices  availi 
lo  them  at  any  time  without  being  forced  to  choose  one  of 
and  without  having  to  remember  command  words  or  special  ke 

The  Menu  Manager  is  the  Apple  IIGS  tool  set  that  supports  menu3 
of  the  style  recommended  by  the  Apple  Human  interface 
Guidclmes.  The  user  displays  a  menu  by  positioning  the  cursor  i 
the  menu  bar  2nd  pressing  the  mouse  button  over  a  menu  »tt& 
The  Menu  Manager  highlights  the  selected  title  (by  redrawing  hi 
mverted  colors)  and  "pulls  down'  the  menu  below  it.  As  long  as 
the  mouse  button  is  hdd  down,  the  menu  is  displayed  Draggingi 
through  the  menu  causes  each  of  its  menu  items  (commands)  to 
be  highlighted  in  turn.  If  the  mouse  button  is  released  over  an 
Item  that  item  is  considered  chosen,  The  item  blinks  brie/ly  to 
confirm  the  choice,  and  the  menu  disappears. 

When  Che  user  chooses  an  item,  the  Menu  Manager  tells  the 
application  which  item  was  chosen,  and  the  application  perforn 
the  corresponding  action.  When  the  application  completes  the  , 
action,  It  removes  the  highlighting  from  the  menu  title,  indicating 
to  the  user  that  the  operation  is  complete. 

If  the  user  moves  the  cursor  out  of  the  menu  with  the  mouse 
button  held  down,  the  menu  remains  visible,  though  no  menu 
Items  are  highlighted.  If  the  mouse  button  is  released  outside  the 
menu,  no  choice  is  made;  the  menu  just  disappears  and  the 
application  takes  no  action.  The  user  can  always  look  at  a  menu 
wUbout  causing  any  changes  in  the  document  or  on  the  screen 
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Menu  bors 


All  oppl  I  cations  should  support 
de^k  accessories.  See 
'Supporting  Other  Desktop 
Features/  later  In  this  chapter, 


Window  mem  bars  are 
cJoicrlbed  under  'Menu 
Manager"  In  the  Apple  liss 
Toolbox  Reference. 


A  menu  bar  is  an  outlined  reciangle  that;  holds  the  titles  of  all  the 
menus  associated  with  the  bar.  A  menu  in  the  bar  may  be  eiiabicd 
or  temporarily  disabled.  A  disabled  menu  can  still  be  pulled 
down,  but  its  litle  and  all  the  items  in  it  are  dimmed  and  not 
selectable. 

The  principal  menu  bar  is  the  system  menu  bar;  see  Figure  5-1 . 
There  can  only  be  one  system  menu  bar  on  the  screen  at  one 
time.  The  system  menu  bar  always  appears  at  the  top  of  the  Apple 
IlGS  screen;  nothing  but  the  cursor  ever  appears  in  front  of  it.  In 
applications  that  support  desk  accessories,  the  first  (leftmost) 
menu  should  be  the  desk  accessory  menu  (also  called  Apple 
menu,  the  menu  whose  litle  is  a  colored  apple  symbol).  The  desk 
accessory  menu  contains  the  names  of  all  available  desk 
accessories,  and  usually  the  name  of  a  dialog  box  that  gives  brief 
information  about  the  application  itself,  ^K^ien  the  user  chooses  a 
desk  accessory  from  the  menu,  the  title  of  the  menu  belonging  to 
the  desk  accessory  may  appear  in  the  menu  bar  for  as  long  as  the 
accessory  is  active,  or  the  entire  menu  bar  may  be  replaced  by 
menus  belonging  to  the  desk  accessory. 


Titles  of  enobled  menus    Titles  of  disabled  menus 


Menu  bar  {_ 


«  File   Edit   View  ■  

LJiiiiiiiiiiiiiiiiiiiiyiiiiiiiiiiiiiiiiiiiiiiyii 


Figure  5-1 

The  system  menu  bar 

In  addition  to  the  system  menu  bar,  your  application  can  have 
various  window  menu  bars.  These  can  appear  anywhere  on  the 
screen  and  in  windows,  Window  menu  bars  are  provided  to  give 
you  more  menu  space,  particularly  because  of  the  limited 
resolution  in  320  mode.  Window  menu  bars  should  be  used 
moderately,  if  at  all. 
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A  Shadowed  rectangle  Is  one  thot 
appears  to  hove  a  thin  shadow 
just  below  and  to  ttie  right  of  It, 
making  It  oppeor  to  ^tand  out 
sllghtt/  from  the  desktop. 


Menu  appearance 

A  standard  menu  consLsts  of  a  number  of  menu  items  listed 
vEitically  inside  &  shadowed  rectangle.  Hems  on  a  menu  maybe 
[he  text  of  a.  commandj  a  solid  color,  or  just  a  line  dividing 
groups  of  choices.  Menus  always  appear  in  front  of  everything 
except  the  cursor.  Figure  5-2  shows  a  menu  with  six  items, 
including  two  dividing  lines. 


Keyboard  equlvolent 
Item 


View 


■ 


Dividing  line' 
Mark 


Disabled  ttem- 


Cut 

Copy 

oC 

Paste 

Clear 

^^how  Clipboard 


Figure  5-2 

A  standard  menu 


Color  

iviiiiiiiiiiiiiilii;' 


Figure  5-2  shows  some  of  ihe  typical  variations  Ln  an  item's 
appearance: 

□  A  mark  may  appear  on  the  left  side  of  the  item,  to  denote  Uis 
status  of  the  item  or  of  the  mode  it  controls, 

□  An  Apple  logo  followed  by  a  capital  letter  may  appear  to  the 
right  of  the  item,  to  show  that  the  item  may  be  invoked  from 
the  keyboard  (that  is,  it  has  a  keyboard  equivaleni).  If  the  user 
presses  the  letter  key  while  holding  down  the  Apple  key,  the 
menu  item  is  invoked  just  as  if  it  had  been  chosen  from  tlie 
menu, 

□  Each  item's  text  may  have  its  own  text  style, 

□  An  item  can  be  dimmed  to  indicate  that  il  is  disabled  and 
can't  be  chosen. 

□  A  dividing  line  is  a  separate  menu  item.  Dividing  lines  should 
always  be  disabled. 


148 


Chapter  5:  Uslrtg  the  Toolbox  (III) 


Ses  "Menu  Manager"  In  the 
Apple  ttGS  Toolbox  Referencefor 
Information  on  how  to  creote 
custom  menus. 


If  a  standard  menu  doesn't  suit  your  needs — for  example,  if  you 
want  more  graphics,  or  perhaps  a  nonlinear  text  arrangement — 
you  can  write  a  custom  menu  definition  procedure.  The  Menu 
Manager  will  call  that  procedure  when  it  draws  the  menu.  The 
custom  menu  can  be  visibly  very  different,  and  yet  respond  to 
your  application's  Menu  Manager  calls  just  like  a  standard  menu. 
The  items  in  the  menu  can  have  any  appearance. 


Keyboord  equivalents 

Your  program  can  set  up  a  keyboard  equivalent  for  any  of  its 
menu  commands  in  order  to  allow  the  user  to  invoke  the 
command  from  the  keyboard.  The  character  you  specify  for  a 
keyboard  equivalent  should  be  a  letier  that  the  user  can  type  in 
either  uppercase  or  lowercase.  For  example,  typing  either  "G"  or 
"g"  wfiile  holding  down  the  Apple  key  invokes  the  command 
whose  equivalent  is  "C5  G,° 

❖  Note-  For  consistency  among  applications,  you  should  specify 
the  letter  in  uppercase  in  the  menu. 


Constructing  menus 

It's  simple  to  construct  your  application's  menus.  All  you  need  to 
do  is  define  the  text  of  the  menu  titles  and  items,  and  assign  ID 
numbers  to  each  menu  title  and  item, 

❖  Nose:  The  menu  bar  does  not  allow  for  a  large  number  of 
menus  or  menus  with  lengthy  titles.  If  you're  having  trouble 
fitting  your  menus  into  the  menu  bar,  you  should  review  their 
organisation  and  tides.  Furthermore,  if  your  program  is  likely  to 
be  translated  into  other  languages,  remember  thai  translated 
menu  titles  may  take  up  more  space. 


Menu  lines  and  item  lines 

You  create  menus  by  constructing  a  list  of  menu  and  item  lines, 
and  passing  a  pointer  to  that  list  to  the  NewMenu  routine, 
NewMenu  parses  the  menu  and  item  lines,  allocates  enough 
memory  for  necessary  records,  and  initializes  those  records.  The 
menu  and  itern  lines  must  remain  in  memory  as  long  as  the  menu 
exists. 
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The  list  must  follow  a.  specific  syntax;  here  is  an  example: 


»Title 

—  Item  string  1\N256 
— Item  string  2\N257 
— Item  strinij  3\N2SB 


For  o  complete  ctiscussion  of 
menu-  and  Item-line  syntax, 
incfuding  a  description  of  all 
sfiedai  characters,  see  "Menu 
Monager'  \ntt^B Apple  tIGS 
Toolbox  Referenca 


This  is  a  simple  list  of  one  menu  line  and  three  item  lines.  The 
first  character  on  the  first  line  is  the  tUle  character;  it  denotes  the 
start  of  a  menu.  The  first  character  on  any  line  other  than  a  tide 
line  Is  the  Hem  character,  it  denotes  an  item  in  the  menu.  The 
second  character  in  each  line  can  be  anything  (it  is  changed  by 
the  Menu  Manager) — here  it  just  repeats  the  first  character  Each 
line  is  terminated  by  a  return  (decimal  13)  or  a  null  byte  (0). 
Finally,  a  termination  character,  different  from  the  menu  and  item 
character,  denotes  the  end  of  the  list. 

In  the  example  above,       is  the  title  character,      is  the  item 
character,  and  a  period  is  the  termination  character.  But  you  mtjl 
use  any  characters,  as  long  as  the  title  and  item  characters  are 
different,  and  the  termination  diaracLer  is  different  from  the  item 
character.  (ITrius,  the  title  and  termination  character  may  be  the 
same.) 

Before  the  terminating  character  of  each  line,  "N"  followed  by  a 
number  specifies  the  menu  and  menu  item  ID  number. 

For  an  example  of  menu  and  item  lines  using  multiple  special 
characters  and  different  title,  item,  and  terminating  characters,  see 
the  riodgePodge  source  code  listing  of  InitGlobals,  under 
"Start  the  Program"  in  Chapter  2.  In  InitGlobals  the  title 
character  is  ">",  the  item  character  is        and  the  termination 
character  is  a  period.  The  second  character  in  each  line  repeals 
the  first.  You  can  see  from  the  listing  that,  depending  on  how  you 
want  your  menus  to  appear,  the  syntax  can  be  quite  complex. 

Using  just  Elie  "@"  symbol  in  a  title  provides  the  Apple  logo.  The 
@  must  follow  the  character  denoting  a  menu  tide,  and  then  be 
followed  by  an  end-of-line  mark  (carriage  return).  Do  not  place  a 
space  before  or  after  the  @,  as  you  must  with  other  menu  titles. 
See  the  InitGlobals  example. 
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Menu  and  item  ID  numbefs 

ID  numbers  are  assigned  in  the  menu/item  line  list.  The  ID 
numbers  musi  be  allocaicd  as  shown  in  Table  5-1. 


Important    A  Menu  ID  must  be  unique  for  each  menu;  that  Is,  no  two  menus  can 
have  the  same  ID.  Similarly,  no  two  itenre.  whether  In  the  same  or 
separate  menus,  can  hove  ttiesome  Item  )D. 


Table  5-1 

Menu  ID  number  assignment 

Htfxadsclmal 

Decimal 

Meaning 

soooo 

0 

iiiterndi  use,  generally  means 
front,  or  first  menu  in  bar. 

S0OOI-$FFFE 

1-65534 

Reserved  for  applies  lion  use. 

SFFFF 

65535 

Internal  use,  generally  means 
end,  or  last  menu  in  bar. 

Item  ID  numbers 

$0000 

0 

Internal  use,  generally  means 
front,  or  first  item  in  menu. 

$0001  -  $00F9 

1-249 

Reserved,  for  desk  accessory 
items. 

$OOFA 

250 

Undo  edit  item. 

$OOFB 

251 

Cut  edit  item. 

3Q0FC 

252 

Copy  edit  item. 

SOOFD 

255 

Paste  edit  item. 

SOOFE 

254 

Clear  edit  item. 

$OOFF 

255 

Close  command  item. 

$0100  -  $FFFE 

256-65534 

Reserved  for  application  use. 

$FFFF 

65535 

Internal  use,  generally  means 
end,  or  last  item  in  menu. 
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Hodgepodge  uses  symbolic  constants  for  menu  ID  numbers  in  its 
menu-  and  item-line  defmitions,  Ii  assigns  menu  ID's  to  those 
constants  m  the  file  GLOBALS  .  pas.  as  follows- 


=  300 

HDout Item 

=  301 

FileHenurD 

—      *|  UL 

Open Item 

=  4Q1 

CXosertem 

=  25S 

SaveAsItem 

=■    4  03 

ChoosePltem 

■=  405 

Pagesetltem 

=  40g 

Print Item 

-  ^07 

Ouitltem 

=  409 

EditMenulD 

=  5D0 

Uncioltem 

=  250 

Cutltem 

=  251, 

Copyltem 

=  352, 

Pasteltem 

"  253; 

Clearltem 

=  254; 

KindowsKenuID 

=  600; 

NoWindowsItem 

=  601; 

FirstWindltem 

-  2  000; 

FontsMenulD 

-  700; 

Fontltem 

=  701; 

Wonoltem 

-  702; 

(reierved  id  number} 
preserved  ID  nu^iber} 
{reserved  id  number) 
i resQived  ID  number  J 
{reserved  id  number) 


(window  menu  iD's  are  allocated 
dynamically  starting  at  2000) 


How  Hodgepodge  sets  up  the  menu  bar  when  the  program 
executes  is  demonstrated  in  Chapter  2. 


Accepting  user  input 


How  your  application  responds  to  menu  selecUons  made  by  the 

WiLhout  TaskNlaster  an  application  typically  call.  GetNextEvent 
e.ch  umc  through  the  event  loop.  If  the  liser  selects  a  menu  item 

1.  It  calls  FindWindow.  which  tin  this  case)  returns  to  the 

.^'Se  me"nutr"'°™''""  "^'^  ^"""-^  P--<i 
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|Iracklng  means  following 
Chonges  In  cursor  position 
Ibetwen  the  time  a  mouse  button 
jlspfessed  and  wti en  it  is  released. 
[That  woy  a  user's  s;electlon  Is  not 
f  Inolized  untii  the  mouse  button  is 
[raleased. 


DoMenu  Is  listed  and  describad 
under  "HandJe  Specific  Events"  in 
Chapter  2. 


2.  1 1  then  calls  Me  nuS  elect,  which  tracks  the  mouse,  opening 
menus  and  highlighting  selections  until  the  mouse  buitoii  is 
released.  If  it  is  released  in  a  menu  selection,  Menu  Select 
returns  to  the  application  the  number  of  the  menu  and  the 
number  of  Lhe  item  in  the  menu  that  was  selected.  It  also 
highlights  the  menu's  title. 

3.  The  application  then  branches  lo  lhe  subroutine  that  handles 
the  menu  item  selected. 

4.  When  the  task  is  completed,  the  application  unhighlighls  the 
menu  title  and  continues  in  ihe  main  event  loop. 

❖  Keyboard  equivaicnt:  If  the  menu  item  was  selected  with  ius 
equivalent  keystroke  combinalion  rather  than  with  the  mouse,  a 
key-down  event  occurs,  'Hie  application  must  look  at  the 
modiriers  field  of  lhe  event  record  to  know  that  the  Apple  key 
was  pressed  at  ihe  same  lime,  meaning  a  menu  selection  has 
been  made.  The  application  then  highlights  lhe  menu  tille  and 
proceeds  from  step  3  (above). 

On  the  other  hand,  if  your  application  calls  TaskMaster  in.^tead  of 
GeUVextEvent  each  time  through  the  event  loop,  most  of  the 
above  procedure  is  handled  automatically,  For  both  mouse-down 
and  key-down  events,  TaskMaster  takes  care  of  finding  out  whether 
ihey  represent  menu-selection  actions.  If  the  user  selects  a  menu 
item  with  the  mouse  or  with  a  keyboard-equivalent,  TaskMaster 
highlights  the  menu  and  returns  a  task  code  of  wlnMenuBar 
(meaning  a  menu  selection  was  made),  Your  application  can 
examine  lhe  laskDaia  field  of  the  extended  task  event  record  to 
see  which  item  in  wliich  menu  was  selected.  Then  it  can  branch 
directly  lo  the  appropriate  subroutine. 

^  Hodgepodge;  Hodge  Podge  uses  TaskMaster.  After  receiving  a 
wlnMenuBar  task  code  from  TaskMaster,  HodgcPodge  jumps 
to  its  menu-event  dispatcher,  Doflenu.  DoMenu  gets  the 
individual  menu  item's  ID  number  from  the  Event  .taskDats 
field  of  the  extended  event  record,  and  jumps  to  the  proper 
subroutine. 
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Modifying  menus  during  execution 


J 


If  your  menu  bar,  or  items  in  a  menu,  are  going  lo  change  while 
on  Lhe  screen,  you  can  use  Menu  Manager  calls  to  rearranee  the 

MeSj^PaT "  " '^""""^  ^'^  '^^''''^  r^^^""^  AddToMenu  (called  from  the 

routine  DoMenu  Item),  HodgcPodge  adds  a  new  item  to  the 
Windows  menu  when  a  new  window  is  opened  on  tlie  desktop, 
AddToMenu  does  this  principally  by  calling  InsertMltem  and 
DeleteMItem.  AddToMenu  also  adjusts  the  window  listr—i  list  of 
pointers  Eo  all  open  windows. 


procedure  AddToMenu; 

war       theWindow      :  GrafPortPtr; 
itryDataHandle:  WindDataH; 

theWindow  :  =  FrontWixidow; 
windowList [windex]    : =  theWindow; 
iT^DataHandle        WindDataH  ( 

GatWRafCoii  (theWindow)  )  ; 

In  saxtMItom  (emyDataHandle^".mernjStr[l], 
$FFFF,Window£MenurD)  ; 

if  windex  =  0  thsn 

Dalat^It*m(NoWindowaItem)  ; 
SatMenuFlag {5FF7F,WindowsMenuID} ; 
D  rawManuBa  r  ; 

end,* 


{begin  AddToMenu...} 


(window-data-reeord  handO.©} 


(Get  a  pointer  to  the  front  window,.,} 
{add  the  pointer  to  the  window  list) 
{-.then  get  a  handle  to  its,..} 
{...window-pdata  record,  to  get  name} 

(Insert  window's  name  at  the  end..,) 
{..of  the  Windows  rnenu} 

(If  this  ia  the  firat  open  window...} 


t„.remove  "No  Windows  ?Lllocated" 
{...enable  the  Windows  menu...} 
(..and  draw  it) 


item} 


CalcMtmuSlsa (0, 0, WindowsMenulD) ; 
Inc (windex) ; 


(Recalculate  the  gize  of  the  inenu} 
{Increment  th^  number  of  open  windows} 
{End  of  AddToMenu} 


The  above  example  shows  how  HodgePodge  add.s  iiems  to  a 
menu.  On  the  other  hand,  when  windows  are  removed  from  the 
desktop,  HodgePodge  deletes  the  corresponding  menu  item  with 
code  in  the  routine  Ad  j  Wind.  Ad  j Mind  is  called  from 
DoCloseltem  when  the  user  selects  Close  from  the  File  menu  or 
when  the  user  dicks  the  close  box  of  the  frontmost  window. 
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I 


flWInd  Is  in  1ti©  source  file  Ad  j  Wind  makes  the  menu-reialed  calls  TnserlMItem,  DcleteMItem 

WINDOW, PAS.  and  CalcMenuSize.  It  also  adjusts  the  window  list  to  reflect  the  fact 

that  a  window  has  been  removed. 


procedure  RdjWind  (TheWindow!  GrafPartPtr> ; 
var 


i 

theOne 


Integer; 
Integer; 


begin 

i  :=  FicstWind; 

while  windowList [i]  <>  TheWindow  do 

Inc  (i) ; 
theOne:-!; 

if  wlndex  =  1  th&n 
begin 

lna«rtMIt«TO(<anQWindStrlll  , 

Fir stWindltem+theOne , 
WindowaMenuIDl ; 
SotManuF lag ( S  0 0 8 0 , Wi  ndow  sMenu I D )  ; 

wXoffset  :-  20; 
wYoffaat  12; 
end; 

Dal etaMItom  ( f  i  rst Wi  ndltem+theOneJ; 
CAlcMonuSlza  (0 ,  0,  l^indowstSenuID)  ; 

Inc  {i); 

MfjiJe  1  <  lastWind  do 
begin 

windowLi  at  [  i  - 1 1   :  "-windowLi  s  t  [  i  ] ; 
Inc  (i); 
and; 

for  i        theOne  to  laatHind  do 
S«tMItaniID   (£iratwindltera+i-l , 
firstWindltem+i) ; 


end; 


(begin  AdjWind,..} 


{start  with  menu  ID  of  1st  window) 
(...and  run  through  the  window  list) 

(..to  get  this  window's  position.) 

{If  we're  closing  the  lAST  window...} 

(...reinaect  "No  Windows  Allocated"...} 

(..After  this  item-.) 

( ...in  the  Windows  menu . } 

(... disable  the  Windows  menu.,.) 

(...redraw  the  snenu  bar„.} 

(...and  reinitialize  the  position,,,) 

(...of  the  next -opened  window) 

{end  of  IF  its  the  last  window} 

{Delete  item  on  the  Windows  menu...} 
{...and  recalculate  size  of  tha  menu) 

(Now  go  to  the  next  window  on  list} 
(..And  for  each  window  in  turn... } 
(move  it  down  one  position..,} 
(...in  the  window  liat) 


{now  renuinber  items  in  Windows  inanu:} 
{its  new  ID  nujnbec} 
{its  old  ID  number) 

(End  of  AdjWind} 


❖  IVotC:  Ad  j  Wind  performs  some  rather  complex  manipulations 
of  pointer  lists  and  menu  IDs.  Your  program  can  easily  remove 
menu  items  without  going  through  such  acrobatics  if  menu  item 
IDs  are  not  going  to  change  and  if  menu  changes  do  not 
require  adjustment  of  other  lists  in  memory. 
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Supporting  other  desktop  features 

Two  other  important  desktop-programming  feaLures  have  tool 
that  suppori  ihem,  'llie  Desk  Manager  controls  desk  accessories 
Ccalled  from  the  Apple  menuj  and  the  Scrap  Manager  handles 
culling,  copying,  and  pasting  from  the  Edit  menu. 


JuEf  What  kind  of  control  an  NDA 
6Kercl£©s  is  described  under 
"Desk  Monoger'  \n  the  Appfe  ItGS 
Toolbox  Reterenca 


Desk  accessories 

Any  application  you  write  should  support  desk  accessories.  Desk 
accessories  are  short  programs  such  as  clock  displays,  note  pads, 
and  caJculaiors  that  a  user  might  want  to  access  without  having  to 
leave  your  program,  Desk  accessory  support  is  a  convenience  far 
the  user,  it  enhances  the  multitasking  feel  of  the  desktop,  and  it  is 
consistent  with  the  aims  of  the  Human  Interface  Guidelines, 
Furthermore,  it's  easy  to  include  in  your  programs. 

The  Desk  Manager  is  the  tool  set  that  enables  your  application 
support  desk  accessories.  There  are  two  types  of  desk  accessories 
in  the  Apple  IIGS  environment:  classic  desk  accessories  and  new 
desk  accessories. 

■  Classic  desk  accessories  (GDA's)  are  desk  accessories  designed 
to  function  in  a  non-desktop,  non-event- driven  environment. 
Unlike  new  desk  accessories,  a  CDA  gets  full  control  of  the 
computer  during  what  is  basically  an  interrupt  state  (generated 
by  a  keypress).  The  desk  accessory  is  resporLsible  for  saving  and 
restoring  any  of  the  application's  memory  that  it  uses,  as  well, 
as  handling  all  I/O.  The  Control  Panel  is  a  classic  desk  j 
accessory. 

■  New  desk  accciisories  (NDA's)  are  desk  accessories  designed 
to  execute  in  a  desktop,  event-driven  environment.  NDA's  tun 
in  a  window  and  get  control  when  that  window  is  the  fronunost 
window. 

*>  Maciniosb  Programmers:  New  desk  accessories  are  the  style  of 
desk  accessories  available  on  the  Macintosh. 
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Sea  'Contf oiling  Itia  Apple  IGS 
OpsfotlnQi  Enviionment'  In  this 
chapter,  and  "Ttie  Scheduler"  in 
ttie  Apple  tiGS  Toolbox  Reference 
for  more  Information  on  thi©  Busy 
1tag. 

II  yoii  want  to  write  0  classic  desk 
occsssofV  (CDA),  see  Chapter  8 
offrilsbook. 


Supporting  ctcssic  desk  accessories 

A  user  activates  a  classic  desk  accessory  from  the  CDA  menu.  The 
CDA  menu  is  displayed  by  pressing  Applc-Control-Escape  at  any 
time  during  program  execution.  Two  CDA's  are  buill  into  the 
system: 

□  Control  Panel 

□  Alternate  Display  Mode 

Any  others  Cup  to  eleven)  are  loaded  from  disk.  From  the  CDA 
menu,  a  user  can  select  any  of  the  CDA's  currently  in  the  system. 
The  desk  accessory  selected  is  activated  and  retains  conirol  until 
it  shuts  down.  When  it  shuts  down,  the  Desk  Manager  redisplays 
the  CDA  menu.  Only  when  the  user  selects  Quit  from  the  CDA 
menu  does  the  original  application  resume  operation. 

When  can  the  CDA  menu  be  displayed?  The  Desk  Manager  gets 
control  in  two  ways.  If  the  Event  Manager  is  active,  the  Desk 
Manager  is  called  in  conjunction  with  GetNexiEvent.  If  the  Event 
Manager  is  not  active,  the  Desk  Manager  gets  control  whenever 
the  user  presses  Apple-Control-Escape,  which  generates  an 
interrupt.  Before  the  Desk  Manager  displays  the  CDA  menu,  it 
checks  the  system  Busy  flag.  If  something  in  the  system  is  busy, 
the  Desk  Manager  waits  until  the  Busy  flag  is  cleared,  then  "wakes 
up"  and  displays  the  CDA  menu.  This  guarantees  that  CDA's  have 
all  system  resources  available  to  them  when  they  are  called. 

The  only  thing  your  application  needs  to  do  to  support  classic 
desk  accessories  is  make  sure  that  interrupts  are  not  disabled  for 
long  periods. 

Supporting  new  desk  accessaries 

New  desk  accessories  are  loaded  automatically  by  the  operating 
system  at  boot  time.  An  application  that  wants  to  make  NDA's 
available  to  the  user  does  not  have  to  do  a  lot  of  work,  particulariy 
if  the  application  is  using  the  Window  Manager  routine  TaskMaster. 
By  convention,  however,  desk  accessories  can  assume  that  the 
following  tool  .sets  are  already  available  for  them  to  use,  so  the 
application  must  make  sure  that  they  are  loaded  and  started  up: 

□  Tool  Locator 

□  Memory  Manager 

□  Miscellaneous  Tool  Set 
D  QuickDraw  II 

□  Event  Manager 
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If  vou  want  to  kvt#©  o  new  desk 
accessory  (NDA).  see  Chapter  a 
ofttiis  book. 


□  Window  Manager 

□  Control  Manager 

□  Menu  Manager 

□  UneEdii  Tool  Set 

□  Dialog  Manager 
O  Scrap  Manager 

Wllh  TaskMastar;  If  ihe  Application  uses  TaskMaster,  it  only  needy 
to  make  three  calls  to  support  new  desk  accessories  after  it  has 
loaded  and  started  up  the  proper  tool  sets: 

o  DeskStartup — to  initialize  the  Desk  Manager 

□  FixAppleMenu — to  add  to  the  list  of  NDA's  in  the  Apple  meiTU 

□  DeskShutdown—to  shut  down  the  Desk  Manager  before  the  ■ 
other  tool  sets  are  shut  down 

After  the  FixAppleMenu  call  has  been  made,  TaskMaster 
automatically  handles  opening  NDA's  in  response  to  menu 
selections,  calling  SystemTask  and  SystemClick  when  appropriate. 
If  the  application  sets  up  the  menu  items  correctly,  TaskMaster 
can  even  call  SystemEdit  when  the  user  selects  an  item  from  the 
Edit  menu,  or  close  a  desk  accessory  in  response  to  the  user's 
selecting  Close  from  the  File  menu. 

<"  Hodgepodge:  The  three  alls  listed  above  are  in  the  routines 
StartUpTools,  SetUpMenus,  and  ShutDownTools. 

Without  TaskMaster:  Applications  that  do  not  use  TaskMaster 
mu5i  lake  the  following  steps  to  support  new  desk  accessories. 

1.  Call  DeskStartup  to  start  up  the  Desk  Manager. 

Z  Call  FixAppleMenu  to  add  to  the  list  of  NDA's  in  the  Apple  rnenlll 

3-  Call  OpenNDA  when  the  user  selects  an  NDA  from  the  Apple 

menu. 

4.  Call  SystemTask  frequently  (at  least  every  time  through  the 
event  loop). 

5.  Call  SystemClick  when  a  mouse-down  event  occurs  in  a  system 
window. 

6.  Call  sSystemEdit  when  a  desk  accessory  is  active  and  the  user 
selects  Undo,  Cut,  Copy,  Paste,  or  Clear  from  the  Edit  menu 

7.  Close  the  desk  accessory  when  the  user  selects  Close  from  the 
File  menu.  You  can  use  CloseNDA  or  CloseNDAbyWinPtr  to  do 
this, 

8.  Call  DeskShutdown  to  shut  down  the  Desk  Manager. 
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Cutting  and  pasting 

An  important  part  of  the  convenience  provided  by  desktop 
applications  is  the  ability  they  give  the  user  lo  transfer  and  copy 
fragments  of  text  or  graphics  within  &  document,  or  from  one 
document  lo  another. 

The  Scrap  Manager  is  the  tool  set  that  lets  an  appMcation  handle 
cutting  and  pasting  of  the  desk  scrap.  From  the  user's  point  of 
view,  all  data  that's  cut  or  copied  resides  in  the  Clipboard.  The 
Cut  command  deletes  data  from  a  document  and  places  it  in  the 
Clipboard;  the  Copy  command  copies  data  into  the  Clipboard 
without  deleting  it  from  the  document.  The  Paste  command — 
whether  applied  to  the  same  document  or  another,  in  the  same 
application  or  another — inserts  the  current  contents  of  the 
Clipboard  at  a  specified  place.  See  Figure  5-3. 

An  application  that  supports  cutting  and  pasting  may  also  provide 
a  Clipboard  window  for  displaying  the  current  contents  of  the 
scrap;  it  may  show  the  Clipboard  window  at  all  times  or  only  when 
requested  via  the  toggled  command  Show  (or  Hide)  Clipboard 

<♦  Nolo;  The  Scrap  Manager  is  designed  to  transfer  small  amounts 
of  data;  attempts  to  transfer  very  large  amounts  of  data  may  fail 
from  lack  of  memory. 


Clipboard  window 


Docurnents 


Flgurd  5-3 

The  Clipboard  and  the  desk  scrap 
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Tin:  Jfisk  £;crap  is  usu-^lly  slored  in  memoiy,  hni  t:t.n  be  stored  en 
disk  (in  [he  file. CLIPBOARD  in  Llic  system  ^ub directory  [jfi.iie 
boot  vn[i.;^ne)  if  there's  not  iinough  room  for  it  in  rriemors;,  The 
Dc^sk  Mana^ej-  keeps  Initi'  of  wliether  tlie  scrsp  is  in  memory  an 
on  die  disk,  :ni  you  don't  have  to  worry  about  ioadiiig  it  firvil, 

Tbe  nrtiiifc  of  the  data  to  be  jransferred  varies  atx:ordi.ng  to  the- 
rrpplicaEioii;  a  wojd  jirocessor  haJidles  frirmaUed  text;  a  grapiiLOi 
a ppii cation  !jy  [idles  pictures,  "11  ic  Scrap  Mana^^er  aUows  f:.>r  a 
vatioLy  of  dsca  types,  and  provides  a  mechanissn  whei^:bj^ 
applications  have  so  me  contra!  over  h:)w  much  information  is 
reuined  wJiijn  data  is  t/ansiencd. 


( 


Desk  scrap  dcttci  types 

FrfHTi  (he  user's  point  rjf  %new  there  can  be  only  one  thin^^  in  the. 
Qipboard  it  a  Liinf.^,  but  tiie  applicaUon  may  ^itbre.mofe  tlind  fine, 
version,  of  the  infofmation  in  tJie  scrap,  Ciich  reprcstiriting  the 
same  .Clipbo^.rd  contents  in  a  rJiffercnt  form.  For  exampic,  text  at 
from  a  word  piocessnr  document  may  i)e  stored  in  the  desk  scra[) 
both     text  arni  ys  a  QuickDraw  II  pitikire. 

Why  would  an  application  want  to  do  tiiis?  Applications  like  to 
kt-ep  information  in  iheir  own  internal  ff:rmat,  but  they  aS^o  wEn.i 
,to  be  able  to  t:omm,un[cate  via  thi:  Clipboard  with  other 
.applicahons.  When  a  user  lil\k  or  copies  sonuj-thing  lo  the 
Clipboard,  the  application  nan  put  it  there  tw(.i  difforeni  ^ays; 

□  Tlie  internal  -way  so  that  a  subsequent  pafitjf!  .(within  the  same 
.application}  can  l:o  easily  hajudled,  PreCi.sely  the  inhirmatioTi 
needed  f^y  iha  apphcation  can  be  transferred. 

CI  The  public  way  so  tiiat  if  tlio  user  tries  to  paste  iy  into  anoihei 
a[iplication  or  desk:  accessory,  the  other  application  can  at  kist, 
deal  with  it,  v.van  if  some  inforniflUon  n^i^^ht  be 

There  arc  two  dchned  p^jljlit:  scrap  types;  toxl  and  picture, 
Applicalions  must  \vrilc  at  least  one  of  these  standard  typrjs  of 
[la  ia  to  the-  desk  ,xcrap,  and  must  bt;  able  ^ to  read  bolJi  (ypes. 

Using  the  Scrap  Mtinagef 

if  your  a  Pi')  11  cation  supporLs  display  of  the  Clij:board,  you  shouf^ 
ca!l  t!ic  Oesk  Manager  each  time  tiia'otjyh  your  main  cvcnl,  loop;^' 
n^a  if  the  Clipboard  window  micds  to  he  update:]. 

T.Yhen  a  <:tit  or  Copy  command  is  given,  use  the  approjiriate  DcJ 
Manager  calts  to  write  the  cut  rir  copied  data  to  ihe-  desk  scjap. 


nhnntrtr        I  tllnn  I'ht-i  Tf-irllhnw  f  wit 


when  a  Paste  command  is  given,  use  oiher  Desk  Manager  calls  to 
access  the  panicular  type  of  data  in  the  desk  scrap  that  you  warn, 
and  to  get  information  about  ihe  data. 

❖  EdU  menu:  The  user  accesses  the  desk  scrap  through  the  Edit 
menu.  Whether  or  not  your  application  supports  cutting  and 
pasting,  it  must  include  an  Edit  menu.  Desk  accessories  may 
need  it 

❖  HodgePodge-  HodgcPodge  does  not  support  cutting  and 
pasting.  It  has  an  Edit  menu,  but  all  items  are  inilially  dimmed 
(disabled). 

Setting  up  a  private  scrap 

If  your  application  defines  its  own  private  type  of  data,  or  if  very 
large  amounts  of  data  might  be  out  and  pasted,  you  may  want  to 
set  up  a  private  scrap  for  this  purpose.  A  private  scrap  can  have 
any  format,  because  no  other  application  will  use  it.  Your 
application  must,  however,  be  able  to  convert  data  between  the 
format  of  its  private  scrap  and  the  format  of  the  desk  scrap. 

If  you  use  a  private  scrap,  be  sure  that  the  right  data  is  always 
pasted  when  the  user  gives  a  Paste  command.  The  right  data  is 
whatever  was  most  recently  cut  or  copied  from  any  application  or 
desk  accessory.  Make  sure  also  that  the  Clipboard,  if  visible,  always 
shows  the  current  data.  You  should  copy  the  conienia  of  the  desk 
scrap  to  your  private  scrap  at  application  stanup  and  whenever  a 
desk  accessory  (NDA)  is  deactivated.  When  your  application  quits 
or  when  a  desk  accessory  is  activated,  you  should  copy  the 
contents  of  your  private  scrap  to  the  desk  scrap. 

❖  LineEdit;  The  LineEdit  scrap  is  a  private  scrap  for  applications 
thai  use  LineEdit.  LineEdit  provides  routines  for  accessing  this 
scrap;  you'll  need  to  transfer  data  tjetween  the  LineEdit  scrap 
and  the  desk  scrap  so  that  the  Clipboard  will  always  be  current. 

❖  Scrap  too  large-  If  your  application  has  problems  copying  one 
scrap  to  another,  it  should  alert  the  user.  If  the  desk  scrap  is  loo 
large  to  copy  to  the  private  scrap,  the  user  may  want  to  leave 
the  application  or  proceed  with  an  empty  Clipboard;  if  the 
private  scrap  is  too  large  to  copy  to  the  desk  scrap,  the  user 
may  want  to  stay  in  the  application  and  cut  or  copy  something 
smaller. 
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Communicating  with  files  and  devices 

The  Apple  IIGS  Toolbox  includes  several  tool  sets  that  handle 
input/output  functions.  They  include 

□  Standard  File  Operations  Tool  Set 

□  Print  Manager 

o  Apple  Desktop  Bus  Tool  Set 

□  Text  Tool  Set 

Using  these  tool  sets  makes  your  application  easier  to  write  and 
ensures  a  uniform  user  interface.  Almost  every  application  needs 
the  Standard  File  Operations  Tool  Set  and  the  Print  Manager; 
fewer  programs  need  the  Apple  Desktop  Bus  Tool  Set  or  the  Tejt 
Tool  Set. 


Accessing  files 

The  Standard  File  Operations  Tool  Set  provides  the  standard  user 
interface  for  selecting  a  file  to  be  opened  or  saved.  The  tool  set 
displays  dialog  boxes  tliat  allow  the  user  to  open  and  save  a  Tile 
on  a  disk  in  any  drive,  and  change  disks  in  a  drive.  The  user  is 
completely  freed  from  having  to  know  how  the  operating  system, 
handles  those  tasks. 

Before  you  make  calls  to  the  Standard  File  Operations  Tool  Set,  it 
must  be  loaded  and  started  up.  If  you  think  it  may  not  be  needed 
every  time  the  program  is  run,  you  can  choose  to  load  the  tool  set 
only  when  you  need  to  present  the  dialog  boxes. 


The  HodgaPodg©  loutlne 
Op&nRrter,  listed  under  "The 
ProDOS  f[la  System'  in  Chapter  6, 
is  on  SMmple  of  how  on 
oppllcQtion  con  filtei  flls  typss  in 
Its  Open  File  dsalog  box 


Opening  a  file 

When  the  user  makes  a  request  to  open  a  file,  your  application 
calls  the  SFGetFile  routine  to  present  the  standard  Open  File 
dialog  box  (Figure  5^4)  and  retrieve  the  filename.  SFGetFile  allows 
you  to  specify  where  the  standard  dialog  box  will  be  placed  on 
the  screen,  to  specify  the  prompt  at  the  top  of  the  box,  and  to 
select,  or  filler,  [he  types  of  files  to  be  displayed  in  the  box.  The 
routine  does  not  allow  you  to  modify  the  appearance  of  the  box; 
if  you  wish  to  construct  your  own  custom  dialog  box,  another 
routine  is  available. 
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Load  which  picture: 
O  /HODCEPODGE/ 

CD  HP.IISM 
CD  HP.CC 
CD  HP.PfIS 
□  PICi 

r     Disk  ) 
IT     Open  3 

D  ?in 

D  mMM. 

C    Cancel  } 

Figure  5-4 

The  Open  File  dialog  box 


In  Hodgepodge,  the  opening  of  a  file  is  initiated  when  the  user 
chooses  Open  from  the  File  menu.  That  menu  choice  causes  the 
execution  of  the  routine  DoOpenltem,  which  calls  openwindow, 
described  in  Chapter  4.  When  opening  a  picture  file  rather  than 
font  window,  OpenWindow  calls  AskUser,  the  routine  that  uses 
Standard  File  Operations  to  select  which  file  to  open.  AskUser 
looks  like  this: 


AsJtUser  is  in  1t\e  source  Til© 
PAINTPAS. 


fuflctiofl    hsWamr:  Boolean; 

vai"        outTyp^List:  TypeListptr; 

begin 

SFGatf ila ( 

20,20, 

■Load  wich  piqtuce:', 
eOpeflFilter, 
Typ«ListReeftr (01  , 
inyReply)  ; 

AskUser  :=  TKLSE; 
if  my Reply . good  tften 
if  LioadOne  then 
AskUser  :-  TRUE; 

end; 


(begin  AskUser...} 

(a  record  that  lists  file  types: 
defined  by  Std.  File  Operations) 


(Gall  up  the  dialog  bojL..} 
(upper-left  comer  =  20,201 
(-  niessage  to  uaer} 
(OpenFilter  screens  file  types) 
(NIL  ptr — show  all  file  types) 
{place  the  results  here| 

{initializB  this  function) 
{if  SFGetFile  not  cancelled.,,) 
{..And  if  the  file  opens  OK...} 
(AaktJser  coirpletea  successfully} 
(End  of  AsltDser} 
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The  connpfete  secruence  of 
routines  that  execute  wtisn  a  file 
Is  opened  is  diagrammed  In 
Appendix  D. 


As  kUser  calls  LoadOne,  which  allocates  the  memory  for  and 
aciually  opens  the  requested  file  by  making  Memory  Manager 
and  ProDOS  l6  caib.  SFGetFile  calls  OpenFilter,  a  routine  that 
controls  which  Lypes  of  files  are  displayed  in  the  dialog  box  and 
how  they  arc  highlighted.  LoadOne  and  OpenFilter  are 
described  in  Chapter  6,  under  "The  ProDOS  File  Syslem." 


Saving  a  file 

When  the  user  makes  a  request  to  save  a  file,  use  the  SFPutFile 
routine  to  present  the  standard  Save  File  dialog  box  (Figune  5-5). 
SFPutFile  allows  you  to  specify  where  the  standard  dialog  box  wftt 
be  placed  on  the  screen,  to  specify  the  prompt  at  the  top  of  the 
box,  and  to  specify  the  maximum  number  of  characters  the  user 
may  type,  Jf  you  wish  to  construct  your  own  custom  dialog  box, 
you  use  another  routine. 


fSi  /HODGEPODGE/ 
Free:  222k  out  of  mt 

C  Disk 

) 

Q  mmuma 

CD  HP.flSM 
CD  HP.CC 
CD  HP.PflS 

DnCl 

C  fffw  Foldei 

) 

) 

) 

Save  which  picture: 

0[  Soue 

1 

(  Cancel 

Figure  5-5 

The  Save  File  d  fa  log  box 


In  HodgePodge,  DoSavelt  em  is  executed  when  the  user  selects 
Save  As  from  tlie  File  menu.  (Check Frontw  makes  sure  thai  Save 
As  is  enabled  only  when  a  picture  window  is  in  front,  because  only 
pS/pAs"^    ''^  picture  windows  can  be  saved.)  Do  Save  Item  first  calls  SFPutFile 

to  bring  up  the  standard  SavcFile  dialog  box,  and  then  calls 
SaveOne,  which  saves  the  contents  of  the  specified  window  to  disk. 
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Dceofure  DoSaveltemj 


(begin  DoSaveltent,..} 


var       theWindow      :  GrafPortPtr; 
myOataHandle :  WindDataH; 
i  :  Integer; 

begLn 

theWineJow        :=  FiontWindoM  ; 
irtyEiataHandle  :=>  WindDatftH( 

SatwrnafCon  (theWiridow)  )  ; 

SFPutFlls  ( 

'Save  which  picture:', 
inyDat  aHandie    .  name , 
15, 

if  irt^'Reply .  good  thart 
-begin 
H&ltCursDr; 

SaveOne  {iryDataHaridle"  "  .  pict )  ; 

with  iryDataHandle"''  do 
begin 

name     :-  ntyReply. fileNajne; 
menuStr:-  ConcatC'-', 

iiryReply .  f  ileName, 
'SH', 

intToStrlng (menuIDl , 
' \0 . ' ) ; 

for  i  :-  firstWind  to  laatWind  do 
if  WindowList [i]  =  theWindow  then 
Leave; 
S«tMIt«tt  ( MenuSt  r , 

FirstWindTtesrtfiJ  ; 

end,- 

SotWTitl*  tmyDaraHandle* " . name, theWindow} ; 
CaloMenuSiza (0, 0, WindowsMenUlD}  ; 
InitCurftor; 

end; 


(pointer  to  a  window} 

{handle  to  our  window-data  record} 


{Get  a  pointer  to  the  front  window) 
(Get  a  handle  to  the  window-data.,.} 
{...record  for  the  window} 
{Bring  up  the  Save  File  dialog...} 
{..^t  location  {20,20)...) 
{...with  this  pronpt  string,..) 
{„.default  =  current  filenaine..,) 
{...allow  15  characters  in  namfi...} 
{...put  answers  in  Reply  record — 
format  specified  by  Std.  Filel 

(If  user  doesn't  cancel...} 
{Put  up  the  watch  cursor  and..) 
{...save  the  file  to  dislc.} 

(Update  our  window-data  record:} 

(Update  the  window  name} 
(NaXe  a  new  menu  string,..) 


(Go  through  the  window-pointer  list:} 
(If  this  vfindow  is  the  one...} 
(„.eKit  from  this  loop} 

{Change  menu  name  to  new  window) 
{end  updating  window-data  record} 

(Update  window  name  to  filename} 
(Resize  menu  for  new  window  name) 
(go  back  to  arrow  cursor} 
(end  of  IF  n^Reply.good=TRUEl 


end,- 


{End  of  DoSaveltera} 


The  disk  writing  is  done  by  ihe  routine  SaveOne.  SaveOne  is 
described  under  "The  ProDOS  File  System"  in  Chapter  6. 

Don'l  forget  to  shut  down  the  Standard  File  Operations  Tool  Set 
after  you  have  finished  using  it — either  right  afterward,  or  with  ihc 
oiher  tool  sets  at  application  shutdown.  If  you  wish,  you  can  also 
unload  the  tool  set  from  memory  and  thus  save  space. 

❖  Noie:  If  you  choose  to  unload  the  Standard  File  Operations  Tool 
Set,  be  sure  to  reload  it  before  making  its  startup  call  again. 
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Printing 

'l"he  Print  Manager  is  an  Apple  IIGS  tool  set  that  allows  you  to  ^ 
standard  QuickDraw  II  routinea  to  print  icxt  or  graphics.  The  PrL« 
Manager  calls  a  printer  driver  to  do  the  spedfic  printing  tasks,  sol 
your  application  doesn't  need  to  know  what  kind  of  printer  is 
connected  to  the  computer.  However,  the  Print  Manager  also 
includes  low-leveJ  calls  to  the  printer  drivers  so  that  you  can 
implement  alternate,  low-level  printing  routines. 

An  application  that  supports  printing  must  have  three  items  initi 
File  menu:  Choose  Printer,  Page  Setup,  and  Print,  Choosing  these 
items  brings  up  dialog  boxes  that  allow  the  user  to  specify  how  s 
document  will  be  printed. 

Choosing  a  printer 

When  the  user  selects  the  Choose  Printer  item,  the  Choose  Printer  j 
dialog  box  is  displayed  (Figure  5-6).  It  lets  the  user  select  a 
destination  device  from  among  the  printer  drivers  on  the  system 
disk.  Tlie  Choose  Printer  dialog  box  ako  lets  the  user  pick  which 
port  or  slot  the  device  is  connected  to,  from  among  the  port 
drivers  on  the  system  disk. 


Choose  Printer 


Printer  type: 


iMflGIWRlTER 


LflSEftWRITERI 


vl.2 


Printer  port: 

EIMlEIia 


HODEH 
PRINTER 


(Cancel  }CqK_J) 


figure  5-6 

The  Choose  Printer  dialog  box 
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DoChooserltem  Is  In  tha  source 
m  PRtNT.PAS. 


If  the  AppleTalk  network  is  installed  and  the  AppleTalk  selection  is 
made  in  the  dialog  box,  the  network  is  scanned  for  Ihs  names  of 
all  connected  printers.  If  one  or  more  printers  of  the  chosen  type 
are  available  on  the  network,  an  additional  dialog  box  appears  so 
that  the  user  can  select  one. 

❖  Macintosh  programmers:  On  the  Apple  IIGS,  the  Choose 
Printer  function  is  part  of  the  Print  Manager,  rather  than  part 
of  the  Chooser  desk  accessory  as  on  the  Macintosh. 

The  liodgePodge  routine  that  brings  up  the  Choose  Printer 
dialog  box  is  called  DoChooserltem.  It  is  called  from  DoMenu. 
when  the  user  selects  Choose  Printer  from  the  File  menu. 


J&ocedure  DoChooserltem; 
var       durtmy  :  Boolean; 

dummy  :=  ?r Choose r.- 


{ begin  DoChooserlteio..) 

(tetutned  value  is  uninportant  here} 


{Bring  up  dialog  box — that's  itl) 
(End  of  DoChooserltem} 


Making  page  settings 

when  the  user  selects  the  Page  Setup  item,  a  Style  dialog  box  is 

displayed  (Figure  5-7).  It  allows  the  user  to  specify  formatting 
information,  such  as  the  page  size  and  printing  oricnlalion.  This 
information  is  not  changed  frequently  and  is  usually  saved  widi 
the  document.  The  LaserWriter  offers  two  style  options 
unavailable  for  the  ImageWriter:  smoothing  of  biunappcd  fonts, 
^nd  font  substitution. 
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iHBGEWRITER/BPPLETaiK 

Poper:  (*)  US  Letter 
OUS  Legal 
O  04  Letter 

O  International  Fenfold 
Ve^ticol  Sijing:  Printer  Effects: 
%)Norjn!Jl  nSiJUeduction 
O  Condensed      O  No  Goes  Between 
Drientdtion:  Pages 


t  Cancel  l^of^ 


DoSetupltem  \s  In  the  source  flle 
PRINT.PAS, 


LflSERWRlTEfi/flPPLETflLK 


vl.l 


Paper;  Eg)  US  Letter  O  HI  Letter 
O  US  Legal  OB5  Letter 
Orientation:       Vertieol  Sizing: 

(S'Normol 
O  Intermediote 
O Condensed 


Printer  Effects: 

^Smoothing? 
^Font  Substitution? 


Reduce  or 
Enlarge: 


C  Cancel  ](|[~Dir]t 


Figure  5-7 

Style  diafog  boxes 

Page  setup  in  HodgePodgc  is  handled  hy  the  routine 
DoSetupltem,  called  from  DoMenu  when  the  user  selecB  Page 
Setup  from  ihe  File  menu.  DoSetupltem  calls  the  Print  Manager 
routine  PrSLlDialog,  passing  it  a  handle  to  a  print  rxicord,  The 
print  record  has  been  allocated  and  initialized  by  the  rouQne 
SetUpDef  ault,  called  at  startup. 


Chopfer  5;  Using  the  Toolbox  (III) 


p-ocedure  DoSetupItem; 
tar       dummy:  Boolean; 


(begin  DoSetOpItem...} 

(function  result  unimportant  here} 


begin 

duiwny  :  = 


PrStlDialog (printHndl } 


{Call  up  the  dial&g,  paas  it 
handle  to  our  print  record) 
(End  of  DoSetupItem) 


the 


Printing 

When  the  user  chooses  to  print  a  document,  usually  by  making  a 
selection  on  ihe  File  menu,  the  Job  dialog  box  is  displayed  (Figure 
5-8).  The  Job  dialog  box  lets  the  user  select  print  quality,  page 
range,  number  of  copies,  and  other  printer-sped  fie  information, 


IHaGWRITER/flPPLETflLK  vl3 

duality:    O  Better  Text 
®  Setter  Color 
O  Draft 

Page  range; 

(§)flll 

OFroin:|^  To:  |  | 
Copies:  jo  I 

paper  Feed:®  flutoaatic  O  Manual 
□  Color  CC^^^Q 


LflSERWRlTER/flPPLETOLK  vll 

Pages:  <S)flll 

OFroni:|^  To:  |  | 

Copies:  [O  | 

Paper  Source; 

(g)  Paper  Troa 

O Manual  Feed  ^ 

[  Cancel  )||(_OK_J| 


Figure  5-fl 

Job  dialog  boxes 
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DoPrintltem  Is  In  ttie  source  fife 
PR  INT.  PAS, 


proced-jre  DoPr intltem; 

var        prPort       ;  GrafPortPtr; 

theWindow:  GrafPortPtr; 


The  Prim  Manager  automaUcally  gives  you  a  QuickDraw  II 
GrafPort  when  you  open  a  document  for  printing.  You  ihen  print 
text  and  graphics  by  drawing  into  this  port  with  QuickDraw  11  caDs 
jus:  as  i/  you  were  drawing  on  the  screen.  The  Print  Manager 
installs  its  own  versions  of  QuickDraw  It's  low-level  drawing 
routines  in  this  GrafPort.  causing  your  higher^level  QuickDraw  n 
calls  to  drive  the  printer  instead  of  drawing  on  the  screen. 

The  Hodgepodge  routine  that  prints  files  is  DoPrintltem,  ca! 
from  DoMenu  when  the  user  selects  Print  from  the  File  menu. 
DoPrintltem  calls  the  routine  PrJobDialog  to  bring  up  the  Job 
dialog  box,  and  then  calls  DrawTopWindow  to  print  the  file: 

{begin  DoPrintltem...) 


beg-in 

theWindow  :=  rrontWindow ; 
if  theWindow  o  NIL  then 

if      JobDlalog (prixitHndl )  then 
begin 

Wa it Cursor, ■ 

prfort   :=  Pi?Dp«iDM(printHndl,NIL)  ; 

PrOpftnPaga (prPoct, NIL) ; 
DrawTopWindow (theWindow)  ; 
PrCloflaPags (prPort) ; 

ParCloaaDoc(prPort  )  ; 
PrPlcFila (printHndl , NIL, NIL) j 
In  it  Cu  r  a  Or ; 

end,' 


(pointer  to  a  printing  GrafPort} 
f window  pointer 1 


{Get  a  pointer  to  the  frori.t  window) 
(If  there  IS  a  window  open...} 
{.iring  up  the  dialog  box;  if^.) 
{...the  user  doesn't  cancel...} 
(put  up  the  watch  cursor...} 
(open  a  printing  GrafPort...} 

(bagln  a  new  [fi  only)  page...} 
{draw  the  contents  of  the  page„.} 
(...cloge  the  page} 

{...close  the  GrafPort} 

(...print  the  spooled  file) 

(..and  restore  the  regular  cursor} 

(end  of  printing} 

(end  of  IF  a  window  is  open} 

{End  of  DoPrintltem) 


DrowTop Window  is  In  the  soufce 
tile  PRINT.PAS. 


See  "Using  the  Print  Manager."  later  in  this  section,  For 
explanations  of  some  of  the  Print  Manager  calls  that 
OoPrintlteminakcs- 

DoPrintltem  calls  the  subrouUne  DrawTopWindow,  which  does 
the  actual  drawing  in  the  printer  GrafPort.  DrawTopWindow  acts 
no  differently  ihan  if  it  were  drawing  to  the  screen;  it  calls  either 
ShowFont  or  Paint  It,  depending  on  what  type  of  window  is  to 
be  printed: 
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procedure  DiraviTopWindow  (TheWindow;VfindowPtr}  ,- 
var       myDataHandle :  WindDataH; 


bsgin 

[ni'DataHandle 


WindDataH  C 

GstWRflfCon  (TheWindowl ) ; 


with  rayDataHandle*"  do 
if  Flag  -  0  che/i 

PaJjitlt  (pict) 
elss 

Show Font (theFont, isMono) ; 


end; 


(begin  DrawTopWindow...} 

Ihajfidle  to  window-data  record  1 


{Get  a  handle  to  the  window's,,, 
[...window -data  record} 


{If  it '  5  a  picture  window...) 
(paint  the  picture  w/this  handle} 
[But  if  it's  a  font  window,,,} 
[draw  text  w/thia  font  &  style) 
(End  of  DrawTopWindow} 


Using  the  Print  Manager 

Print  records:  Before  you  can  print  a  doHCument,  you  need  a  valid 
lbs  structurs  of  o  print  record  Is  print  record.  The  print  record  describes  information  such  as  page 

(hown  In  tfie  Appla  tIGS  Tocfbox  dimensions  and  resolution.  You  can  cither  ujie  an  existing  print 

Reference  record  (for  instance,  one  saved  with  a  document)  or  create  one 

through  Print  Manager  calls.  HodgePodge  uses  the  same  print 
record  for  all  documents.  That  record  can  be  modified  by  the 
user  through  the  Style  and  Job  dialog  boxes. 

*  Note;  Whenever  your  application  saves  a  document,  it  should 
save  an  appropriate  print  record  with  the  document.  Tliis  sets 
up  the  printing  parameters  for  the  document  so  that  they  can 
be  used  the  next  time  the  document  is  printed. 


I  m  p  o  r  1  d  n  I    In  nnost  Instances  your  appll  cation  should  not  d  I  rectly  charge  tti© 
data  in  the  print  record— it  should  use  ttie  standard  dialog  routines 
for  changing  this  Inforrralion,  Attempting  to  set  certain  volues 
directly  in  the  print  record  can  produce  unexpected  results. 


Draft  and  spool  printing:  There  are  two  basic  methods  of 
printing  documents:  draft  and  spool. 

r  In  draft  printing,  your  QuickDraw  11  calls  are  converted  directly 

into  command  codes  the  printer  understands,  which  are  then 

I  immediately  used  to  drive  the  printer.  The  LaserWriter  always  uses 

J  draft  printing,  because  Ihe  QuickDraw  II  calls  are  traa^latcd 

;  immediately  into  PostScript  commands.  The  ImageWriter  and 

j  other  nonintelligent  doi  matrix  printers  are  written  lo  in  draft 

•  mode  for  text  only  High-quality  pixel  images  are  produced  by 

I  spool  printing. 
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Compare  this  sequence  of  call^ 
with  fhe  listing  of  the  Hod9ePocfg& 
routine  DrowIopWindow,  earlier 
In  this  section. 


In  spool  printing  ihe  Print  Manager  prcxresses  your  printing 
rcquesbi  in  iwo  sleps,  Firsi  it  writes  out  Cspools)  a  representalioa  fif 
your  document's  printed  image  lo  a  disk  file  or  to  memory. 
Second,  this  information  is  converted  into  a  bit  image  and 
printed.  This  method  is  used  lo  print  graphics  on  the 
I  mage  Writer. 

The  printing  loop:  To  print  a  document,  you  call  the  following 
routines: 

1.  PiOpcnDoc,  which  returns  a  pointer  to  the  GrafPort  to  be  us 
for  printing 

Z  PrOpenPage,  which  starts  each  new  page  (reinitializing  the 
GrafPort) 

3.  QuickDraw  routines,  for  drawing  the  page  Into  the  port  creat 
by  PrOpcnDoc 

4.  PrClosePagc,  which  terminates  the  page 

5.  PrCloseDoc,  ai  the  end  of  the  entire  document,  to  close  the 
GrafPort  being  used  for  printing 

6.  PrPicFile,  to  print  the  spooled  document 

Steps  2  through  4  are  the  priming  loop  itself;  they  are  repeated  tor 
as  many  pages  as  are  printed.  Each  page  is  either  printed 
immediately  (draft  printing)  or  written  to  disk  or  to  memory 
Cspool  printing).  Your  application  may  inspect  the  print  record  lo 
see  whether  spooling  was  done,  but  it  doesn't  have  lo.  The  proper 
method  is  always  selected  automatically,  and  PrPicFile  is  execu" 
only  if  needed. 

You  should  check  for  errors  after  each  Print  Manager  call.  If  an 
error  occurs  and  you  cancel  printing  (or  if  the  user  aborts 
printing),  be  sure  to  exit  properly  from  the  printing  loop  so  tha 
all  files  are  dosed  correctly— that  is,  be  sure  that  every 
PrOpcnPage  is  matched  by  a  PrClosePage,  PrOpcnDoc  is 
matched  by  PrCloseDoc,  and  PrPicFile  is  still  called. 

<*  Note:  The  maximum  number  of  pages  in  a  spool  file  is  16,382 
If,  for  some  strange  reason,  you  need  lo  print  more  than  l6, 
pages  at  one  time,  just  repeat  the  printing  loop. 
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Transfer  rmodGS  are  discussed 
under  'Drawing  to  the  Screen."  in 
Chapter  3, 


QuickDraw  II  consequences  and  I  imitation*:  Even  though  you 
print  by  making  QuickDraw  calls,  remember  ttiai  printing  lo  paper 
is  not  really  the  same  as  drawing  to  the  saeen.  Clipping  regions 
and  character  spacings  don'i  translate  exactly.  Erasing,  of  course, 
can't  be  done  on  a  printer.  Some  transfer  modes  and  some 
drawing  routines  don't  work  on  a  LaserWriter.  For  more 
information  about  optimizing  your  printing  code,  see  the  Apple 
Has  Toolbox  Reference  and  the  LaserWriter  Reference. 

Background  procedure:  An  optional  background  procedure 
runs  whenever  the  Print  Manager  has  directed  output  to  the 
printer  and  is  wailing  for  ihe  primer  to  finish.  It  is  typically  a 
dialog  box  that  informs  the  user  that  a  print  job  is  in  progress, 
and  allows  the  user  the  option  of  ca.nceling  it. 

if  you  don't  designate  a  background  procedure.  Ihe  Print  Manager 
uses  a  dcfauU  procedure  for  canceling  printing;  the  default 
procedure  just  polls  the  keyboard  and  sets  a  Print  Manager  error 
code  if  the  user  presses  Apple-Pedod.  If  you  use  this  option,  you 
should  display  a  dialog  box  during  printing  to  inform  the  user 
that  the  Apple-Period  option  is  available, 


Itve  multlple-segiTiBnt  sannple 
fKOQtam  listed  under  "Creating 
Segmented  Coci&;  Thres 
Examples"  in  Chapter  7  Includes 
calls  to  the  Text  Tool  Set. 


The  Pascal  and  BASIC  character 
davlce  drivers  are  discussed  In 
Itie  Appis  !SGS  Film  ware 
Ssfsienca 


Sending  text  to  Apple  II  character  devices 

If  you  are  writing  a  native-mode  Apple  IIGS  application  but  don't 
want  to  use  QuickDraw  IJ  and  the  graphic  desktop  interface,  you 
may  need  the  'lext  Tool  Set.  It  provides  an  interface  between 
Apple  11  character  device  drivers,  which  mu.st  be  exetruted  in 
emulation  mode,  and  new  applications  running  in  native  mode.  It 
also  provides  a  means  of  redirecUng  I/O  through  RAM-based 
drivers,  'ITie  Text  Tool  Set  makes  it  possible  to  deal  with  the  text 
screen  without  switching  65816  processor  modes  and  moving  to 
bank  zero.  Dispatches  to  RAM-based  drivers  still  occur  in  full 
native  mode. 

The  Text  Tool  Set  has  global  routines  that  are  used  to  set  or  read 
the  current  global  parameters  used  by  R.'^AI  and  the  Pascal  and 
BASIC  text  drivers.  The  tool  set  also  has  I/O  directing  routines 
that  direct  I/O  from  ihe  tool  set  to  a  specific  type  of  character 
device  driver,  or  request  information  about  the  directing  of  a 
specific  I/O  driver.  Finally,  ihe  tool  set  has  text  routines  Uiat 
interface  widi  any  BASIC,  Pascal  11,  or  llAM-based  character 
device  driver.  See  "Text  Tool  Set"  in  the  Apple  IIG5  Toolbox 
Reference  for  more  details. 
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ComnnunicaHng  with  Apple  Desktop  Bus  devices 

The  Apple  Desktop  Bus  CADB)  is  &  hardware  channel  and  a 
protocol  for  connecting  input  devices,  such  as  keyboards  and 
mouse  devices,  with  personal  cornputers.  The  personal  computer 
is  considered  to  be  the  host  during  the  commuiiication,  and 
controls  the  communication  on  the  bus  by  issuing  ADB 
commands  to  the  devices, 

The  Apple  Desktop  Bus  Tool  Set  sends  commands  and  data 
between  the  Apple  Desktop  Bus  miCTocontroller  and  the  rest  of 
the  system.  Typically,  the  tool  set  is  used  to  control  ADB  activity, 
but  other  commands,  which  are  used  by  diagnostic  routines  and 
the  Control  Panel,  are  available. 

Most  applications  have  no  need  to  use  the  ADB  Tool  Set  ' 
However,  if  your  program  needs  lo  modify  the  system's  interface 
with  the  mouse,  keyboard,  or  other  ADB  device,  the  ADB  Tool  Set 
is  indispensable. 

More  details  about  the  bus  can  be  found  in  the  Apple  IICS 
Firmware  Reference  and  the  Apple  IIOS  Hardware  Reference.  The 
tool  set  is  described  under  "Apple  Desktop  Bus  Tool  Set"  in  the 
Apple  IIGS  Tbolbox  Reference. 


Making  sounds 

The  Apple  IIGS  has  a  very  advanced  sound-generation  system, 
capable  of  creating  and  reproducing  complex  music,  sound 
effects,  and  speech,  Sound  tools  at  several  levels  give  you  access 
to  the  sound  hardware  and  make  music  generation  easy. 


The  sound  hardware 


The  Apple  IIGS  sound  hardware  supports  two  sound-gene  rati  or 
methods.  In  the  first  method,  which  replicates  the  Apple  lie  sound 
capabilities,  an  application  toggles  a  soft  switch  which  in  turn 
generates  clicks  in  a  speaker.  The  application  can  control  the  rate 
of  clicking  and  the  volume  of  the  speaker. 
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The  second  method  uses  a  digital  oscillator  chip  CDOC)  and  the 
rest  of  the  sound  hardware,  as  diagrammed  in  Figure  5-9:  64K  of 
dedicated  RAM,  ihe  Sound  GLU  (general  logic  umt),  the  analog 
section,  and  the  sound  connector. 


IIGSI/O- 


Sound 
GLU 


64K 
RAM 


Speaker 
Toggle 


Analog 


DOC 


SoLind 
ConoBctor 


forfurttief  Intbrmallon  on  the  DOC. 
zee  tiie  Apple  ItGS  HardMOis 


Figure  5-9 

Sound  hardware  block  diagram 

The  sound  GLU  acts  as  the  I/O  interface  between  the  Apple  lIGS 
system  hardware  and  the  sound  hardware.  The  dedicated  RAM 
stores  the  waveforms  used  for  sound  generation.  From  them  the 
IX>C  can  create  sounds  of  practically  any  pitch  and  duration. 

The  analog  section  contains  all  the  circuitry  needed  lo  amplify 
and  filter  the  signal  coming  from  the  Sound  GLU  or  the  DOC. 
From  there  the  signal  is  sent  to  the  speaker. 
The  sound  connector  provides  the  connection  lo  interface  cards 
that  can  take  the  tones  generated  by  the  DOC  and  modify  them 
further.  Three  examples  of  possible  sound  cards  are 
programmable  filter  cards,  stereo  interface  cards,  and  sound 
sampling  cards. 


Oscillators  and  generators 

An  oscillator  is  the  basic  sound-generating  unit  in  the  DOC, 
DOC  contains  32  oscillators,  each  of  which  can  function 
independently  from  all  the  other  oscillators. 


Making  sounds         1 75 


The  System  Failure  Monager  Is 
described  under  "MiEcelianeoui 
Tool  Sef '  In  me  Apple  ilGS 
Toolbox  Reference. 


See  "Sound  Tool  Sat*  in  the 
Apple  liGS  Toolbox  Referencetof 
details  on  both  high-level  (free- 
fofm  synthesizeO  and  low-level 
colls. 


One  of  the  modes  of  the  DOC  is  called  swap  mode.  The  Sound 
Tool  Set  (described  next)  uses  this  mode  to  generate  sounds  In 
swap  mode,  a  pair  (siiap  pair)  of  oscillators  forms  a  amctional 
unit  called  a  generator.  T^ere  are  15  generators  defined  in  the 
Apple  lIGS  sound  system.  The  oscillators  in  a  generator  take  turns 
making  sound,  each  signaling  the  end  of  its  sound  by  generatins 
an  interrupt. 

Oscillators  30  and  31  are  reserved  for  system  use  and  should  not 
be  be  used  by  applications.  If  an  inieroipt  is  generated  by 
oscillator  30  or  31  it  is  a  fatal  error— a  sound  interrupt  is  reported 
to  the  System  Failure  Manager,  which  halls  execution, 


The  Sound  Tool  Set 

The  Sound  Tool  Set  gives  you  the  ability  to  access  the  sound 
hardware  without  having  to  know  specific  hardware  I/O  addresses 
Sound  Tool  Set  calls  can  be  divided  into  two  groups  hiah-Ievel 
and  low- level. 


High-level  calls  constitute  ihe /ree/orm  synthesizer.  Calls  to  the 
free-form  synihesijcr  are  made  through  the  normal  tool  call 
mechanism,  with  parameters  being  passed  to  and  from  the  called 
routmcs  on  the  stack,  With  high-level  calls  you  can 

□  wriie  multibyie  sound  data  to  and  read  it  from  DOC  RAM 

□  get  or  set  the  volume  of  individual  generators 

□  start  and  stop  sound  on  an  individual  generator 

Low-level  routines  read  from  and  write  lo  the  DOC  hardware 
registers  and  individual  DOC  RAM  locations.  Unlike  the  other 
Sound  Tool  Set  routines,  which  use  the  stack  to  pass  parameters  in 
the  normal  tool  call  fashion,  these  routines  use  registers  to  pass 
parameters  and  are  entered  through  a  jump  table.  The  low-Icvei 
roulmes  can  move  information  faster  than  ihe  higher-level  calls 
to  the  free-form  synthesizer,  but  they  do  none  of  the  error 
checking  and  housekeeping  of  the  higlier-levcl  routines 
r-urihermore,  if  you  use  the  low-level  routines,  you  will  have  io 
mstall  your  own  interrupt  handler  to  service  sound  interrupts 


I 
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The  Note  Synthesizer 


The  Note  Synthesizer  gives  your  application  a  convenient  way  to 
play  musical  notes.  You  me  ihe  Note  Synthesizer  by  making  tool 
calls  to  start  and  slop  individual  notes,  The  general  sequence  of 
calls  is  something  like  this: 

1.  Allocate  an  individual  generator. 

Z  Start  a  note,  with  the  NoteOn  call  The  call's  parameters  specify 
the  generator  to  play  the  note  on,  the  note's  volume  and  pitch, 
and  what  instmment  to  use.  An  Instrument  is  a  data  structure 
that  specifies  such  parameters  as  the  amplitude  envelope 
(attack  and  decay  shapes),  pitchbend  and  vibrato 
characteristics,  and  the  specific  waveforms  that  characterize  the 
sound  to  be  played, 

3,  Stop  the  note  with  the  KoteOff  call-  When  the  note  stops 
playing,  the  generator  is  automatically  deallocated. 

The  Note  Synthesizer  provides  for  priority  in  allocation  of 
individual  generators.  If  all  generators  are  in  use,  generators 
producing  low-priority  sound  Csuch  as  notes  trailing  ofQ  can  be 
"stolen"  to  produce  higher- priority  sounds  {such  as  notes  starting 
up).  Priority  assignment  can  assure  that  there  will  always  be  a 
generator  available  when  a  note  needs  to  be  played, 

❖  Enable  interrupts:  Interrupts  must  be  enabled  in  order  for  the 
Note  Synthesizer  to  function.  Anything  that  disables  interrupts 
(such  as  accessing  a  disk  drive)  will  disrupt  the  sound  being 
played. 


The  Note  Sequencer 

The  Note  Sequencer  is  the  tool  set  that  makes  it  easy  for  you  to 
include  music  in  your  programs.  In  particular,  it  allows  music  to 
be  played  asynchronously,  in  the  background. 

The  Note  Sequencer  builds  upon  the  Note  Synthesizer,  in  that  it 
strings  together  individual  notes  created  by  the  sythesizer. 

You  can  think  of  the  Note  Sequencer  as  a  cross  between  a  player 
piano  and  a  language  interpreter.  A  sequence  is  a  series  of 
commands  that  tell  the  computer  which  notes  to  play  and  when. 
The  Note  Sequencer  plays  back  that  sequence  to  generate  muscial 
sound. 
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MIDI  stands  tor  Musical  tnsifumBnt 
Digital  Interfoce.  an  internatlonaf 
sfandord  tor  electronic  transfer  of 
musical  dotQ. 


Sequences  are  built  up  from  simpler  components.  Individual 
commands  to  the  Sequencer  are  called  items.  Items  typically  tu 
a  note  on  or  off,  or  control  some  aspect  of  the  note's  sound,  sa 
as  vibrato.  Items  are  assigned  to  one  or  more  tracks,  to  fadlitata 
the  concept  of  multi-instrument  music  and  chords,  A  pattern  is  i 
scries  of  itcnxs;  the  pattern  groups  those  items  in  terms  of  their 
mutual  timing  reJationshipw. 

A  phrase  is  a  set  of  pointers  to  patterns  or  to  other  phrases. 
Phrases  make  it  easy  to  build  repetitive,  complex  passages  out 
simple  patterns.  A  sequence  is  a  top-level  phrase^  one  which 
points  to  patterns  or  other  phrases  but  is  not  pointed  to  by 
other  phrases, 

You  play  music  with  the  Sequencer  by  making  a  StartSeq  call . 
plays  a  specified  sequence.  In  intermpi  mode,  the  sequence  is 
played  automatically  until  it  finishes.  Jn  itep  mode,  your 
application  can  play  the  sequence  item-by-item.  Step  mode  is 
useful  if  you  need  to  synchronize  the  sequence  with  other  events 
In  your  program. 

❖  Enable  intemipts:  Imcraipts  must  be  enabled  in  order  for  the 
Sequencer  lo  function.  Anything  that  disables  internipts  (such 
as  accessing  a  disk  drive)  will  dismpt  the  sound  being  played. 

❖  MIDI:  The  Sequencer  is  not  directly  compatible  with  the  MIDI 
protocol  If  you  wish  to  communicate  with  a  MIDI  synthesizier 
on  your  Apple  JIGS,  you  will  need  to  install  a  MIDI  interface 
card  or  a  MIDI  serial  adapter  (manufactured  for  the  Macintosh 
Plus),  At  the  time  of  this  writing,  there  are  no  software  tools  to 
allow  the  Note  Synthesizer  or  Sequencer  lo  manipulate  MIDI 
data. 


Computing 

If  your  applications  require  mathematical  compuutions  on  either 
integers  or  Hoating-point  numbers,  there  are  Apple  IIGS  tool  sets 
that  provide  you  wiih  fast,  consistent,  and  accurate  algorithms. 
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Integer  Math 

The  Integer  Math  Tool  Set  supports  muliiplicaiion  and  division  of 
several  types  of  numbers,  and  also  coriverts  numbers  from  one 
type  to  anoLher.  The  types  of  numbers  dealt  with  are  these: 


integer  l6-bit  signed  or  unsigned  value 

longint  32-bit  signed  or  unsigned  value 

fixed  32-bit  signed  value  with  16  bits  of  fraction 

frac  32-bit  signed  value  with  30  bits  of  fraction 

extended  80-bit  signed  value  with  64  bits  of  fraction 


❖  Note:  The  extended  type  really  serves  as  a  pathway  to  the 
Standard  Apple  Numeric  Environment.  See  the  next  section  in 
this  chapter,  "High -Precision  Floating-Point  Math  (SANE)." 

The  Integer  Math  Tool  Set  also  manipulates  Integer  Math  strings, 
which  are  ASCII-string  representations  of  numbers.  An  Integer 
Math  siring  consists  of  only  digits  (hexadecimal  or  decimal)  and 
blanks  and  has  no  lengih  byte  within  it 

Within  the  tool  set,  there  are  math  routines  and  Integer  MMh 
string  routines.  Math  routines  support  multiplication  and  division 
of  integer,  long  integer,  fixed,  and  frac  numbers,  perform  simple 
trigonometric  calculations,  and  conven  from  one  type  of  value  to 
another.  Integer  Math  string  routines  convert  between  a  binary 
value  and  an  ASCII  character  string  representing  that  value.  The 
binary  value  can  be  either  an  integer  or  a  long  integer.  The 
character  string  can  be  in  either  hexadecimal  or  decimal  format. 

Your  application  can  make  use  of  the  Integer  Math  routines  at  any 
time;  tlie  tool  set  is  always  active.  Furthermore,  the  Integer  Math 
Tool  Sei  does  not  rely  upon  the  presence  of  any  other  tool  sets. 


High-precision  floating-point  math  (SANE) 

For  high-precision  calculations  on  floating-point  numbers,  your 
application  should  use  the  Standard  Apple  Numerics 
Environment  (SANE).  SANE  is  a  collection  of  routines  that 
perform  extended-precision  IEEE  arithmetic,  with  elementary 
functions.  SANE  scrupulously  conforms  to  IEEE  standard  754  for 
binary  floating-point  arithmetic  and  to  the  proposed  IEEE 
standard  854,  which  is  a  radix-independent  and  word-length- 
independent  standard  for  floating-point  arithmetic. 
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Additional  informotlon  on  SANE 
routines  is  found  under  'SANE 
Tool  Set"  In  the  Apple  UGS 
Todbox  reference 
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SANE  provides  sufficient  numeric  support  for  most  appIicaU 
includes 

□  IEEE  types  single  G2-bit),  double  C64-bit),  and  extended  m 
bit) 

□  a  64-bit  type  for  large-inieger  computations,  as  in  accounting 

□  fundamental  floating-poini  operalions  C  +  -  *  /  V  rem  ) 


I 


Q  comparisions 

□  binary-to-decimal  and  floaling-point'to-intcger  conversions 

□  scanning  and  formatting  for  ASCII  numeric  strings 

□  logarithm ics,  trigonometries,  and  exponentials  || 

□  compound  and  annuity  functions  for  financial  computations 
a  a  random  number  generator 

□  functions  for  management  of  the  noating-point  environment 

□  other  functions  required  or  recommended  by  the  IEEE 
Standard 
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The  Apple  11 GS  SANE  tool  set  matches  the  functions  of  the 
Macintosh  SANE  packages,  and  the  6502  assembly-language  SAH 
software  from  which  it  is  derived. 

The  functions  of  SANE  are  completely  documented  in  the  Appit 
Numerics  Manual,  which  you  will  need  if  you  are  going  to  use  Ih 
routines  in  your  application. 


Controlling  the  operating  environment 

Many  components  make  up  the  Apple  TIGS  operating 
environment,  she  overall  hardware  and  software  setting  within 
which  application  programs  run.  Several  tool  sets'  principal 
functions  are  to  control  and  modify  that  environment.  You  mig 
call  them  low-level  tool  sets,  in  contrast  to  the  higher-level, 
desktop  interface  tools. 

The  Event  Manager,  described  earlier,  and  the  Memory  Manag, 
and  System  Loader,  described  in  the  next  chapter,  are  three  of  i 
most  important  tool  sets  in  diis  group.  Two  others  are  the 
Miscellaneous  Tool  Set  and  the  Scheduler,  described  here 
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The  Miscellaneous  Tool  Set 


The  Miscellaneous  Tool  Set  is  a  collection  of  several  small  tool 
sets.  Most  of  them  set  or  return  information  about  various  low- 
level  functions  of  the  Apple  HQS.  Several  other  managers  and  tool 
sets  make  calls  lo  the  Miscellaneous  Tool  Set. 

Many  of  the  routines  in  this  tool  set  retrieve  the  address  or  return 
the  value  of  a  given  parameter  so  that  your  program  need  not  rely 
on  fixed  addresses.  Please  use  these  calls  instead  of  directly 
accessing  memory  locations;  there  is  no  guarantee  that  an  address 
being  used  for  something  in  one  version  of  system  software  will 
be  used  the  same  way  in  subsequent  versions. 


Parametfir  RAM.  also  known  os 
Butteiy  MM,  (etalris  clock- 
calandar  and  Control  Panel 
Wormotlon  whsn  the  computer 
powsj  Is  off, 


Tick  count  CappmxImateJy)  the 
numbef  at  60fri-second  Intsfvafs 
elapsed  sines  system  startup. 

For  more  informotlon  about 
Interrupt  sources  and  nandlers. 
iBB  ttie  jA|Pp;e  lies  Flrmwara 
Reference  and  (hsAppSeltss 
PtoDOS  16  aaferenCB. 


Groups  of  rotjtines 

□  You  can  use  iialtery  /MAf  routines  to  write  and  read  data  to 
and  from  parameter  KAM.  Any  data  written  to  parameter 
RAM  will  affect  Ihe  default  system  configuration,  which  will  be 
used  the  next  time  the  system  is  booted. 

□  The  clock  routines  provide  you  with  a  way  to  read  the  current 
lime  either  in  hex  or  ASCII  format,  or  set  the  current  time  using 
hex  format.  The  GetTick  routine  reads  the  current  tick  count. 

□  Vector  routines  set  or  return  the  vector  address  for  a  specified 
interrupt  manager  or  handler.  Interrupt  control  routines  allow 
your  application  lo  enable  or  disable  certain  interrupt  sources 
and  gel  the  current  status  of  those  interrupts. 

□  Address  and  entry  routines  return  the  addresses  and  native- 
mode  entry  points  of  some  important  firmware  parameters  and 
routines. 

□  The  HeariBeat  routines  allow  you  to  install  or  delete  tasks  from 
tlie  HeariBeat  Interrupt  Task  queue.  Such  tasks  might  include 
controlling  cursor  movement,  or  posting  a  disk-insert  event,  or 
checking  the  stack.  They  are  called  at  some  multiple  of  every 
"hearlbeat"  (vertical  blanking  interval),  60  times  a  second. 

□  The  System  Failure  Manager  fo\x^ne  allow^s  you  to  customize 
the  system  failure  message.  Thus,  if  the  user  causes  your 
application  to  crash,  you  can  have  the  System  Failure  Manager 
display  a  message  that  gives  the  user  an  idea  of  what  happened. 
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□  The  User  ID  Manager  routines  create  and  delete  the  numbera 
by  which  thie  ownership  of  ail  allocated  memory  blocks  is  j 
specined.  Every  program  on  tlie  Apple  liGS  has  a  User  ID, 
assigned  by  the  User  JD  Manager;  each  block  that  Ihe  Memory 
Manager  allocates  for  that  program  is  given  the  program's  I 
User  ID. 

o  The  rnouse  routines  allow  your  application  to  directly  set  or  g{ 
the  mouse  location.  However,  the  Event  Manager  calls  these 
routines  auiomatically,  so  most  applications  don't  need  to  i 
make  the  calls.  If  you're  not  using  the  Event  Manager  or 
TaskMaster,  you  may  need  to  use  the  mouse  routines.  ' 

□  The  PackBytas  routine  packs  data  to  make  a  file  smaller,  'nnis 
can  be  useful  for  such  things  as  graphic  images,  which  would 
ordinarily  take  up  too  much  space  on  disk.  UnPackEytes 
unpacks  the  data  from  the  PackBytes  format.  | 

□  The  Munger  routine  allows  your  application  to  manipulate 
strings  easily. 

a  Jha  SysBeep  routine  causes  the  system  speaker  to  beep. 

"The  Miscellaneous  Tool  Set"  in  the  Api^le  IIGS  Toolbox 
Reference  describes  in  detail  all  of  the  above  groups  of  routines 

I 

The  Scheduler 

The  Scheduler  is  a  tool  set  that  delays  the  activation  of  a  desk 
accessory  or  other  task  until  the  resources  that  the  desk  accessory 
or  task  needs  become  available.  Much  of  the  system  code  is  not 
reentrant;  that  is,  the  code  cannot  be  called  again  while  it  is 
executing.  Because  of  that,  activating  a  desk  accessory  within  non- 
reentrant  code  almost  always  causes  the  system  to  fail.  Thus,  the 
Apple  lies  provides  a  Busy /lag  that  the  Scheduler  can  check  to 
discover  if  a  needed  resource  is  busy  or  available. 

To  write  a  typical  application,  you  won't  need  to  use  the 
Scheduler.  Even  if  you  are  writing  a  classic  desk  acccessoiy  you 
won't  need  to  call  the  Scheduler— the  Desk  Manager  does  it  for 
you,  Perhaps  the  only  time  you  need  to  use  it  is  when  you  are 
writing  interrupt  handlers  tliat  access  ProDOS  16  or  the  toolbox 
routines,  For  example,  an  appIicaUon  that  performs  background 
prinUng  might  need  to  access  the  Scheduler. 
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Tha  Scheduler  is  campletely 
docLmentsd  under  'The 
Setieduier'  in  tho  Apple  liGS 
Toolbox  Referencs. 


Scheduler  maintains  a  queue  of  tasks  waiting  to  execxite,  and 
consults  the  Busy  flag  before  dispatching  them.  When  a  non- 
reetxiram  module  is  entered,  your  interrupt  handler  should  set  the 
Busy  flag;  when  exiting  from  the  module,  the  application  should 
clear  the  Busy  Rag,  permiiUng  the  Scheduler  lo  execute  any  Usks 
that  have  been  placed  in  its  queue. 

Your  imerrupl  handler  should  therefore  check  the  state  of  the 
Busy  flag  before  it  calls  any  system  software.  If  the  word  is 
nonzero,  the  necessary  system  resources  are  not  currently 
available,  and  you  should  add  your  task  to  the  Scheduler's  queue. 
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Chapter  6:  Memory.  Segrrents,  ond  Fifes 


For  a  complet©  description  of 
Memory  Manogsf  functions,  see 
'Memory  Manager'  in  the  Appfe 
lIGS  Toolbox  Reference. 


What  the  Memory  Manager  does 

The  Memory  Manager  is  a  ROM-fesident  Apple  IIGS  tool  set  that 
conu-ols  the  allocation,  deallocation,  and  repositioning  of 
memory  blocks  in  the  Apple  ncS,  The  Memory  Manager  works 
closely  with  ProDOS  l6  and  the  System  Loader  to  provide  the 
needed  memory  spaces  Tor  loading  programs  and  data  and  for 
providing  I/O  butrers.  All  Apple  UGS  software,  including  the 
System  Loader  and  ProDOS  16,  must  obtain  needed  memory 
space  by  making  calls  to  the  Memory  Manager. 

The  Memory  Manager  keeps  track  of  how  much  memory  is  free 
and  what  parts  are  allocated  to  whom.  Memory  is  allocated  in 
blocks  of  arbitrary  length,  each  block  possesses  several  attributes 
that  describe  how  the  Memory  Manager  may  modify  it  (such  as 
moving  it  or  deleting  it),  and  how  it  must  be  aligned  in  memory 
(for  example,  on  a  page  boundary).  Table  6-1  describes  the 
memory  block  attributes  and  lists  the  predefmed  constants  with 
which  each  can  be  specified. 


Tabl»  «-l 

Memory  block  ottributes 


Altilbulv 


Constant' 


Explanation 


Fixed  (yes/no) 


Fixed  address  (yes/no)  attrAddr 

Fixe d  bank  Cy e s/no)  attrBank 

Bank-boundary  limited  Cyes/no)  attrNoCrosa 

Special  rnemory  not  usable  Cyes/no)  attrNoSpec 


Page-aligned  Cyes/no) 
Purge  level  CO  to  3) 

Locked  Cyes/no) 

'  Equivalent  to  "yes"  if  present 


attrFixed         Must  the  block  remain  at  the  same  location 
in  memory? 

Must  it  be  at  a  spedRc  address? 

Must  it  be  in  a  particular  memory  bank? 

Is  it  prohibited  from  extending  across  a 
bank  boundary? 

Is  it  prohibited  from  residing  in  banks  SOO, 
$01,  and  parts  of  banks  $E0,  $E1? 

attrPage  Must  it  be  aligned  to  a  page  boundary? 

attrPurge         Can  it  be  purged  Cmade  available  for  other 
use)?  If  so,  with  what  priority? 

attr Locked        Is  the  block  locked  Ctemporarily  fixed  and 
unpurgeable)? 
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The  System  Loader  Is  described 
under  "Loading  Programs  ond 
Segmenfs,*  later  In  tfils  chaptei. 
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❖  Hodgepodge:  For  an  example  of  the  use  of  prcdermed 

constams  Ccolumn  2  of  Table  6-1)  in  specifying  memory-block 
attributes,  see  any  of  I-Todge Podge's  NewHandle  calls— such  as 
in  the  routine  StartUpTools  (Chapter  2).  See  also  "How  Yout; 
Application  Obtains  Memory,"  later  in  this  section. 

Memory-block  attributes  are  specified  in  an  attributes  word. 
When  you  request  a  block  of  memory,  you  supply  the  attributes 
word  for  that  block.  Later,  you  can  modify  the  value  of  the 
attributes  word  to  change  the  block's  characteristics. 

In  addition  to  creating  and  deleting  memory  blocks,  the  Memory 
Manager  moves  blocks  wlien  necessary  lo  consolidate  free 
memory  and  relieve  meniDry  fragmenmUon,  When  it  compacts 
memory  in  this  way  (Figure  6-1),  the  Memory  Manager  can  move 
only  those  blocks  that  needn't  be  fixed  in  location.  Therefore  as 
many  memory  blocks  as  possible  should  be  movable  (not  fixed), 
if  the  Memory  Manager  is  to  be  efficient  in  compaction.  Data 
segments  and  segments  containing  posltlan-lndependent  code 
can  generally  be  placed  in  movable  blocks. 


Before  compaction. 


After  compoctton 


Fixed  blocks  Movable  blocks  Ffee  memory 
Figure 

Memory  frag  men  totioo  and  compaction 
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Pointers  and  handles  to  memory  blocks 


To  access  an  enlry  point  in  a  movable  block,  an  applicaiion  can- 
not use  a  simple  pointer,  because  the  Memory  Manager  may  move 
the  block  and  change  the  entry  point's  address.  Instead,  each  time 
the  Memory  Manager  allocates  a  memory  block,  it  returns  to  the 
requesting  application  a  handle  referencing  that  block. 

A  handle  is  a  pointer  to  a  pointer:  it  is  the  address  of  a  fixed  (non- 
movable)  location  that  contains  the  address  of  the  block.  If  the 
Memory  Manager  changes  the  location  of  the  block,  it  updates  the 
address  in  the  fixed  location;  the  value  of  the  handle  itself  is  not 
changed.  Thus  the  application  may  continue  to  access  the  block  by 
using  the  handle,  no  matter  how  often  the  block  itself  is  moved  in 
memory. 


Memory  block 


a.  Pointer: 

Value  oi  pointer  = 

starting  address  of  memory  block 

$xxx   


S>CXX 


Memory  block 


Hondi*: 

Value  of  handle  = 
address  of  master  pointer 


szzz 


Flgur«  6-2 

Pointer  and  handle 


sxxx 


Master  pointer 


■SZZ2 


sxxx 


If  a  block  will  always  be  in  the  same  place  in  memory  (that  is 
cither  locked  or  fixed),  it  may  be  referenced  by  a  pointer  instead 
of  by  its  handle.  To  obtain  a  pointer  to  a  particular  block  or 
location,  an  application  can  dereference  the  block's  handle.  The 
application  reads  the  address  stored  in  the  location  pointed  to  by 
the  handle — ihat  address  is  the  pointer  to  the  block.  Of  course,  if 
the  block  is  ever  moved  that  poir^ter  is  no  longer  valid 
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In  most  high']evel  languages,  dereferencing  is  a  simple,  singl©- 
statement  task.  For  example,  in  C  Ihe  statement 


Deref 


START 

sta  0 
stx  2 
Idy  #4 

Ida  [0],y 
iSSOOO 

(0],y 


ora 

dey 
dey 
Ida 
tax 
lda[0] 
rta 
END 


[OJ,y 


dereferences  the  memory  handle  y.  The  variable  z  now  co 
a  pointer  to  Ihe  memory  block  whose  handle  is  y.  In  assembly- 
language  it  takes  a  few  more  statements;  the  HodgePodge  routine 
Deref  On  the  file  GLOBALS  .  ASti)  looks  like  this: 


store  low  word  of  handle  at  ^ero-page  address  0 
stare  high  word  ot  handle  at  ^ero-page  address  2 
put  the  value  "4"  in  V  register 
set  the.,. 

...attributes  bit  that... 
-.locks  the  block 
now  Y=3 
now  t=2 

put  high  word  of  pointer  into  acumulator 
put  high  word  of  pointer  in  X  register 
put  low  word  o£  pointer  in  accumulator 
return  to  caller 


A  memory  handle  thaf  points  to  o 
value  of  zero  Is  calledNIL 


When  a  memory  block  is  purged,  the  memory  that  iis  handle 
pointed  to  becomes  available  for  other  use  but  the  handle  itself 
remains  in  memory.  A  purged  memory  handle  points  to  the 
address  $00  0000,  but  retains  its  User  ID  and  all  its  attributes  as 
listed  in  Table  6-1,  so  that  the  memory  block  can  be  quickly  and 
easily  reallocated  if  necessary. 

Wlien  all  the  attributes  of  a  memory  handle  as  well  as  the 
memory  it  points  to  are  discarded,  the  handle  is  said  to  be 
disposed.  A  disposed  memory  handle  is  no  longer  associated  wth 
a  particular  program,  Your  application  can  get  rid  of  memory  it 
no  longer  needs  by  making  a  DisposeHandle  call. 

Pointers  and  handles  must  be  at  least  3  bytes  long  to  access  the 
full  range  of  Apple  JIGS  memory.  However,  pointers  and  handles 
passed  as  parameters  are  always  4  bytes  long,  because  they  are 
then  easier  to  manipulate  in  the  l6-bit  registers  of  the  65C816 
mi  crop  roce  ssor. 


Important 


Do  not  us©  me  high-order  byte  of  q  4-bvte  pointer  or  handie  to 
store  data.  The  unused  byte  la  reservod  for  system  use-your 
application  should  always  fill  it  witti  zeros, 
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How  your  application  obtains  memory 


When  an  applicalion  makes  a  call  to  the  operating  system  or 
other  system  software  that  requires  allocalion  of  memory  (such  as 
opening  a  file  or  writing  from  a  file  lo  a  memory  location),  the 
system  software  first  obtains  any  needed  memory  blocks  from  the 
Memory  Manager  and  then  performs  its  tasks.  When  an 
application  informs  the  operating  system  that  it  no  longer  needs 
that  memory,  the  information  is  passed  on  to  the  Memory 
Manager  which  in  turn  frees  that  application's  allocated  memory. 
In  these  cases  the  memory  allocation  and  deallocation  is 
completely  automatic,  as  far  as  the  application  is  concerned. 

Requesting  memory 

Any  other  memory  lhac  an  application  needs  for  its  ow^n  purposes 
must  be  requested  directly  from  the  Memory  Manager.  The 
shaded  areas  in  Figure  6-3  represent  those  parts  of  the  Apple  IIGS 
memory  that  can  be  allocated  through  requests  to  the  Memory 
Manager.  Apple  lies  applications  should  avoid  requesting 
absolute  (fixed-address)  blocks — it  defeats  the  Memory  Manager's 
ability  to  allocate  memory  as  efficiently  as  possible,  and  increases 
the  probability  that  the  program  will  not  be  able  to  load  or  run. 


Figure  6-2 

Memory  olSocatable  through  Ihs  Memory  Manager 


Th&  Memory  Manoger  Is  fn  charge! 
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Your  appIicaUon  requests  memory  with  the  Memory  Manager's 
NewHandJe  call.  Her^:  is  an  example  from  HodgePodge: 


tooiiZeroPaije 


:-  NewHandls (Total DP, 

myMemorylD, 


Dfrscf.page  spocQ  \s  d&scfJbed 
Jn  mof  9  defalf  later  in  ttiis  chapter. 


attrBank+attrFixed+attrLocked+attrPaae 

In  ihis  example  HodgePodgc  i,  requesting  direct-p.ge  space  for 
tool  set  use.  ToolsZ^roPage  i.  a  handle  to  the  requested  .pace. 
Input,  to  the  caJl  are:  size  (Tct^lDP).  User  ID  (myMlmoryiD) 
prcdefmed  constant,  specifying  attributes  (as  described  M  Table 
6-1  J,  and  a  pointer  to  where  the  block  is  to  begin  (bank  $00  in  i 


Ttie  User  ID  Manager  Is  dascrlbed 
under  "MiscellonGous  Too[  Set' 
in  th©  Apple  ttGS  TooSjox 


User  IDs 

Many  Memory  Manager  calls  use  the  block's  User  ID  a  code 
number  that  shows  what  program  owns  the  memory  block  User 
IDs  are  assigned  by  the  User  ID  Manager. 

When  your  application  starts  up  the  Memory  Manager  the 
operat.ng  system  has  already  assigned  a  master  User  m  for  that 
execuiion  of  the  application.  The  operating  system  gives  the 

Tses  .,:r,n     '° '^^'"•^^  ^^^-s--  -^-^  - 

Passes  iliat  ID  to  your  application  in  the  MMSianUp  call  You 
must  save  that  ID  for  use  when  you  shut  down  your  appI^catSt 


Byte  1 

ByteO 

Bit; 

15  1  14 

13 

12 

111  1 10 1  9  la 

6  ,  5  ■  d  '  3  '  2  1 

1  in 

Value: 

typeiD 

OUXlD 

mainlD  J 

Figure  6-4  ' 

User  ID  fornnat 


t^Jjm  '^^'^^         ^^ee  fields-the 

typcID.  auxip.  and  mainID  field^contained  in  a  word-length 
parameter^The  value  in  the  inali^D  field  is  assigned  by  the  uLrl 
Manager  The  typelD  field  contains  a  number  that  describ^  tS  , 
genera  k.nd  of  program  segment  that  will  occupy  the  b"  cT-^ch 
as  apphcation.  desk  accessory,  or  tool  set  The  a^ID  HeldlT  ' 

value  IS  0;  your  application  can  store  any  4-bit  value  there 
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Using  the  auxID  field,  your  applicalion  can  create  up  to  15  new 
and  distinct  User  IDs  from  the  single  master  User  ID  returned  by 
the  Memory  Manager  at  startup.  You  can  use  each  new  User  ID  to 
allocate  as  many  additional,  private  memory  blocks  as  needed; 
when  finished  with  the  memory  allocated  under  a  particular  ID, 
discard  it  all  at  once  by  calling  DisposeAll  with  that  ID.  An 
example  of  this  technique  is  shown  in  the  following  assembly- 
language  code  fragmeni 

puslTword  #0  ;  space  for  master  User  ID 
_HM3tartUp 

pla  ,-  retrieve  master  User  ID 

sts  MasterlD  ;  store  master  User  ID 

era  #50100  ;  create  User  10  with  AUX  ID  -  1 

sta  MylD  ;  store  ID  for  use  w/  private  memory 

%  *  m 

;    (your  code  here) 

*  *  * 

...  ;    (ready  to  eKit  program) 

pushword  MylD 
DisposeAll      ;  discard  all  of  ray  private  memory 
...  1    (continue  with  termination 

...  ;  process ingf 


lmpoftqn>    Do  not  specily  an  ouxlO  of  0<  The  Memory  Mcmoger  roufines 

PurgeAll  and  DisposeAll  treat  an  quxID  field  wWh  0  In  It  as  a  wildcard 
ttiQt  matches  all  values. 


The  main  advantage  of  this  method  is  that  you  can  dispose  of  all 
allocated  blocks  quickly  and  easily,  with  a  DisposeAll  call,  instead 
of  making  sure  to  keep  track  cf  all  allocated  blocks  and 
deallocating  them  individually, 

You  don't  have  to  use  lliis  method  You  could  simply  use  the 
master  User  ID,  unchanged,  lo  obtain  new  private  memory. 
However,  your  application  could  not  then  use  the  DisposeAll  call 
to  discard  everything— it  would  be  disposing  of  itself  too.  Another 
method  is  lo  obtain  an  entirely  new  User  ID  for  private  memory. 
This  method  allows  you  to  discard  all  private  memory  at  once, 
but  leaves  open  the  possibility  of  allocated  blocks  remaining  in 
memory  after  your  application  quits. 

❖  HodgePodge:  HodgePodge  makes  very  few  memory- allocation 
requests.  It  uses  an  unmodified  master  User  ID  when  11  does  so, 
and  it  makes  sure  lo  dispose  of  ils  requested  memory  blocks 
individually. 


The  Memory  Manager  Is  In  charge  I 


193 


Importanf 


For  more  (nforrmotlon  on  memorv 
mooogement,  see  tha  Appte  nes 
Toolbox  Referenc&and  Ih© 
Apple  llGSPraDOS  16  Reference. 

Important 


Locking  ond  unlocking,  purging  and  disjMsirtg 

If  KOu  need  lo  access  a  movable  memory  block  directly— that  is 
you  need  to  derefcnence  its  ha^dle-^you  must  Orst  lock  it  so  that 
it  won  E  move  while  you  are  using  U.  When  you  no  longer  need  it 
to  be  locked,  make  sure  to  unlock  it  so  the  iMemory  Manager  can 
move  It  during  compaction.  Don't  iocli  blocks  that  you  are  not 
currently  accessing. 

If  you  are  temporarily  ihrough  using  a  block,  and  don't  mind  if  i 
contents  must  be  rcconsuucted  tiie  next  time  thev  are  needed 
you  can  set  the  block's  purge  level  to  make  it  purgeable  Then' 
Memory  Manager  can  purge  it  if  more  space  is  needed  If  tile 
Memory  Manager  does  purge  a  Mock,  you  can  quickly  restore  it 
with  the  same  attributes.  User  ID,  and  size. 


When  the  Memoty  Manager  purges  q  block,  all  daia  in  It  is  lost  ¥c 
appl-CQ  ion  Is  responsible  for  saving  and  restoring  the  data 
appropriately,  " 


When  your  application  is  completely  Tinished  with  its  own  priva 
memory  It  should  dispose  of  it^for  example,  by  calling  the 
DisposeA  l  routine  and  spedfying  the  User  ID  with  a  modified 
^uxID  neld.  as  described  earlier.  If  your  application  doesn't 
dispose  of  all  memory  that  it  has  acquired,  the  memory 
management  system  can  become  clogged. 


Do  not  call  DisposeAII  with  ttie  unmodified  master  User  ID  for  your 
own  progrom  (the  one  In  which  ouxlD  =  0).  ^ 


The  System  Loodsr  fs  described 
In  ttiQ  next  section  of  this  chapter. 


Load  segments  and  memory  blocks 

In  Chapter  1  we  introduced  the  idea  of  segmented  programs  TTie 
.xecutab  e  versions  of  program  files  are  ^Iled  load  files ^dtTe. 
consist  of  one  or  more  lo.d  segment..  Load  segments  a^e  ^ 
placed  m  memory  by  the  System  loader.  The  System  Loader  m^si 

se^tnK    '  ^'^'"^^  '^^"^^^^  because'dilTerent  type^ 

segments  require  memory  blocks  with  different  attributes. 

When  the  system  Loader  loads  a  program  segment,  it  calls  the 
Memory  Manager  to  allocate  a  memory  bloc?  for  t^e  segment 
The  attributes  assigned  to  that  memory  block  are  closely  Ued  o 
the  attributes  of  the  segment  that  will  inhabit  the  block 
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If  the  program  segment  is  static,  and  therefore  must  not  be 
unloaded  or  moved,  its  memory  block  is  marked  as  unpurgeabls 
and  fixed.  That  means  that  the  Memory  Manager  cannot  change 
that  segment's  position  or  contents  as  long  as  the  program  is 
running.  If  the  program  segment  is  dynamic,  its  memory  handle  is 
initially  marked  as  purgeable  but  locked  (temporarily  unpurgeable 
and  fixed;  subject  to  change  at  the  request  of  the  application).  If 
the  dynamic  segment  is  position-independent,  its  memory  handle 
is  marked  as  movable;  othenvise,  it  is  fixed. 

In  summary,  a  typical  load  segment  will  be  placed  in  a  memory 
block  that  is 

□  locked 

□  fixed 

□  purge  level  =  0  (that  is,  unpurgeable)  if  the  segment  is  static 

□  purge  level  =  1  if  the  segmenL  is  dynamic 

Depending  on  other  requirements  ihe  segment  may  have,  such  as 
alignment  in  memory,  the  load  segment- memory  block 
relationship  may  be  more  complex.  Consult  the  Apple  IIGS 
ProDOS  16  Reference  for  details. 


Loading  progfams  and  segments 

The  System  Loader  loads  all  programs  and  segments  of  programs. 
It  is  called  by  ProDOS  16  when  an  application  starts  or  quits,  it  is 
called  automatically  to  load  dynamic  segments  during  program 
execution,  and  it  can  be  called  by  your  application  to  load  and 
unload  other  programs  or  program  segments.  This  section 
describes  both  the  automatic  operation  of  the  loader  and  the 
ways  in  which  your  program  can  call  it  directly. 

❖  Note:  If  you  are  writing  a  typical  application,  you  don't  have  to 
call  the  System  Loader  at  all.  All  its  operations  are  automatic 
for  most  programs,  even  those  with  dynamic  segments.  If  you 
are  not  interested  in  System  Loader  details,  skip  ahead  to 
"Quitting  and  Launching  Under  ProDOS  I6." 

❖  Hodgepodge:  Hodgepodge  makes  no  loader  calls. 


Loading  programs  and  segments 
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The  System  Loader,  although  a 
tool  set,  i$  documented  in  the 
Appla  lies  ProDOS  16  ReferencQ 


The  Jump  Table,  Pathname 
Tobla,  and  other  System  Loader 
tabtes  ore  discussed  In  detail  in 
the  Apple  liGS  ProDOS  16 
ffeferenca 


How  the  System  Loader  works 

The  System  Loader  is  ihe  Apple  IIGS  tool  set  that  manages  the 
loading  of  program  segments  into  the  Apple  IIGS.  It  works  very 
closely  wiih  the  Memory  Manager  and  with  the  ProDOS  l6 
operating  system. 

The  System  Loader  is  a  program  that  processes  load  files — it  is 
not  concerned  with  source  files  or  object  files.  Each  load  file 
consists  of  ioad  segments  that  the  loader  treats  differenily, 
depending  upon  their  attributes: 

■  Static  segments  are  loaded  into  memory  ai  application  startup. 
They  stay  in  memory  until  the  program  quits. 

■  Dynamic  segments  arc  placed  in  memory  only  as  needed 
during  program  execution.  They  may  be  removed  when  no 
longer  needed. 

■  Absolute  segments  are  loaded  al  specified,  fixed  locations  in 

memory, 

■  Relocatable  segments  are  placed  wherever  the  System  Loader 
can  find  siilTicient  memory  space.  Once  they  are  loaded,  their 
memory  blocks  are  locked  so  they  can't  move. 

■  Position-Independent  segments  are  placed  wherever  the  System  I 
Loader  can  fmd  sufficient  memory  space.  Their  memory  bloda 
are  initially  locked,  but  once  urilocked  they  can  be  moved  froa  | 
one  location  to  another  between  executions. 

Some  load  segments  consist  of  typical  program  code  or  data; 
others  are  more  specialized.  The  Jump  Table  segment,  when 
loaded  into  memory,  becomes  the  Jump  Table^  it  provides  a 
mechanism  by  which  segments  in  memory  can  trigger  the  loading 
of  other  needed  segments.  The  Pathname  segment  becomes  the 
Pathname  Table,  a  cross-reference  between  pathnames  on  disk 
and  load  segments  in  memory.  An  Initialisation  segment 
contains  any  code  that  has  to  be  executed  first,  before  the  rest  of 
the  segments  are  loaded. 

When  the  System  Loader  is  called  to  load  a  program,  it  loads 
static  load  segments  and  constnjcts  the  tables  necessary  to  allow 
automatic  loading  of  dynamic  segments. 
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'  Controlling  program  so  re 

■  dKussed  under  "Loodlng 

i  ApplicQtlons,"  lotet  (n  this  section. 


To  unload  a  segment,  the  System  Loader  calls  the  Memory 
Manager  to  make  the  corresponding  memory  block  purgeable.  If 
the  segment  is  dynamic,  the  loader  also  alters  the  Jump  Table  to 
reflect  the  fact  that  the  segment  may  no  longer  be  in  memory. 

To  unload  all  segments  associated  with  a  particular  application 
(for  example,  at  shutdown),  a  controHing  program  such  as  a  shell 
calls  the  System  Loader's  User  Shutdown  function,  which  in  turn 
calls  the  Memory  Manager  to  make  purgeable,  purgCj  or 
dispose  of  the  application's  memory  blocks  (depending  whether 
the  application  is  rcstartable  or  not — see  "Shutting  Down  and 
Restarting  Programs  in  Memory,"  later  in  this  section). 


Loading  a  relocatable  segment 

When  a  relocatable  segment  is  loaded  into  memory,  its  code  is 
placed  at  the  location  assigned  to  it  by  the  Memory  Manager.  The 
loader  then  performs  relocation  on  the  code — it  patches  address 
operands  that  refer  to  locations  both  within  and  external  to  the 
segmem. 

1  Local  references  are  coded  in  the  load  segment  as  offsets  from 
the  beginning  of  the  segmenL  The  loader  adds  the  starting 
address  of  the  segment  to  each  offset,  so  that  the  correct 
memory  address  is  referenced, 

2  External  references  may  be  to  routines  in  static  or  dynamic 
segments.  If  the  reference  is  to  a  static  segment,  the  loader 
finds  the  memory  location  of  the  routine  in  that  static  segment 
and  patches  the  reference  with  its  address.  If  the  reference  is  to 
a  dynamic  segment,  the  loader  patches  the  reference  to  point 
to  a  Jump  Table  entry.  The  Jump  Table  entry  contains  the 
information  necessary  to  transfer  control  to  the  external 
segment  when  it  is  loaded. 

You  can  see  that  most  Apple  IIGS  code  cannot  be  moved  once  it 
is  in  memory:  relocation  happens  only  when  the  segment  is 
loaded,  so  if  the  segment  is  ever  moved  its  address  operands  will 
no  longer  be  correct.  Only  position-independent  code,  which 
needs  no  relocation,  can  be  moved  around  in  memory.  And 
position -in  dependent  code  is  difficult  to  write — therefore,  most 
Apple  lies  code  is  relocatable,  but  not  position-independent. 
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Objoct  modulB  formal  Is  th&  flla 
format  produced  by  Apple  IGS 
(Jevelopmenf  systems  such  as 
the  Apple  IBs  Programmer's 
Workshop.  See  Chopter  7. 


Loading  applications 

The  funciioning  of  the  System  Loader  is  completely  transpar 
to  most  applications.  Any  program  that  is  in  proper  object 
module  format  (wiih  any  combination  of  static  and  dynamic 
segments)  will  be  automatically  loaded,  relocated,  and  executed 
whenever  it  is  called,  Unless  you  want  your  program  to  load 
dynamic  segments  manually,  or  load  and  execute  other  pzogiat, 
you  need  not  know  how  to  use  the  System  Loader. 

However,  you  can  indirectly  affect  the  functioning  of  the  System^ 
Loader  by  the  method  in  which  you  segment  your  programs.  If 
your  program  is  divided  into  static  and  dynamic  segments,  you 
may  experiment  with  several  configurations  of  a  single  program 
after  it  has  been  assembled  to  see  how  loading  of  dynamic 
segments  affects  performance.  See  Chapter  7  for  further  progiaa 
design  considerations  involving  static  and  dynamic  segments, 

Application  control  of  segment  loading 

Most  applications  do  not  need  to  make  loader  calls  direaly, 
for  programs  with  specialized  requirements  the  System  Loader 
offers  this  capability. 

One  advantage  of  manually  loading  a  dynamic  segment  is  that 
segment  can  be  referenced  in  a  more  direct  manner  ttian  an 
automatically  loaded  dynamic  segment.  Automatically  loaded 
dynamic  segments  can  be  referenced  only  through  a  JSL  to  the 
Jump  Table;  however,  if  the  segment  consists  of  data  such  as  a 
table  of  values,  you  would  want  to  simply  access  those  values 
rather  than  passing  execution  to  the  segment.  By  manually 
loading  the  segment  into  a  locked  memory  block,  and 
dereferencing  its  memory  handle  (obtaining  a  pointer  to  the  s 
of  the  segment),  you  can  then  reference  any  location  in  the 
directly.  Of  course,  because  the  loader  does  not  resolve  any 
symbolic  references  in  the  manually  loaded  segment,  the 
application  must  know  the  segment's  exact  structure. 

Your  program  is  responsible  for  managing  the  segments  it  loads, 
Tliat  is,  it  must  unload  them  with  System  Loader  calls  when  they 
are  no  longer  needed. 
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Looding  by  controlling  programs  (shells)' 


ill8  PtoDOS  16  QUIT  call  is 
explaln&d  under  'Qurtting  and 
Launching  Under  ProDOS  16/  later 
h this  chapter, 


More  d  Sid  led  requlrementB  for 
controlling  programs  ond  their 
subprogfoms  Ccallsd  shell 
applicalions)  are  listed  In 


A  program  may  cause  the  loading  of  another  program  in  one  of 
[WO  ways: 

□  The  program  can  make  a  ProDOS  16  QUIT  call.  ProDOS  l6 
and  the  System  Loader  remove  the  quitting  program  from 
memory,  then  load  and  execute  the  specified  new  program. 

□  The  program  can  call  the  System  Loader  directly.  The  loader 
loads  the  specified  new  program  without  unloading  the  original 
program,  then  hands  control  back  to  the  original  program, 

Most  applications  use  the  first  method.  Even  if  you  want  your 
applicaiion  to  launch  another  specific  program,  and  even  if  you 
want  control  to  return  to  your  application  after  the  succeeding 
program  quits,  the  ProDOS  l6  QUIT  call  is  all  that  is  needed.  For 
example,  a  finder  or  program  launcher,  which  always  regains 
control  between  execution  of  applications,  uses  the  QUIT  call  to 
launch  the  applications. 

Programs  thai  use  the  second  method  are  called  controlling 
programs.  Certain  types  of  finders,  switchers,  and  shells  may  be 
controlling  programs.  ProDOS  l6  is  a  controlling  program;  the 
Apple  IIGS  Programmer's  Workshop  Shell  is  a  controlling 
program.  An  application  needs  to  be  a  controlling  program  only 
if  it  must  remain  in  memory  after  it  calls  another  program,  usually 
because  it  has  functions  or  sets  up  an  environment  needed  by  the 
programs  it  executes. 

The  controlling  program  is  completely  responsible  for  the 
subprogram's  ultimate  disposition.  When  the  subprogram  is 
finished,  the  controlling  program  must  remove  it  from  memory 
and  release  all  resources  associated  with  its  User  TD.  The  best  way 
to  do  this  is  to  call  the  System  Loader's  User  Shutdown  function. 


Shutting  down  and  restarting  programs  in  memory 

liy  using  System  Loader  calls,  a  controlling  program  can  rapidly 
switch  execution  among  several  applications.  For  switching  to  be 
efficient,  the  loader  must  be  able  to  shut  a  program  down  without 
removing  it  from  memory,  and  the  program  must  be  able  to  re- 
execute  Itself  without  having  to  be  reloaded  from  disk. 


Loading  progranns  ond  segments 
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Resfaitqble  5oftiwar&  reinitializes 
Its  variobles  evary  tims  it  gains 
contfol;  It  olso  mokes  no 
assumptions  about  ths  stote  of 
ttie  machJne  it  will  find  wtiem  It 
starts  up. 


The  User  Shutdown  function  can  put  an  application  into  such  a ! 
dormant  state.  Ii  does  this  by  purging  an  application's  dynamic] 
segments,  and  making  ail  its  sialic  segments  purgeable.  This 
process  frees  space  but  keeps  the  dormant  application's  essenLi^J 
segments  in  memory,  As  long  as  all  the  sialic  segments  are  sttU  j 
memory,  [he  Restart  function  brings  the  application  back  rapid 
because  disk  access  is  not  necessary.  However,  if  for  any  reason-] 
the  Memory  Manager  purges  one  of  those  static  segments,  the 
application  can  no  longer  be  restarted — the  next  time  it  is 
needed,  it  must  be  loaded  from  its  disk  file. 

Only  software  that  is  restartable  can  be  executed  in  this  way.  In 
general,  if  your  program  has  a  code  routine  ihat  defines  and 
initializes  all  variables,  and  if  that  routine  is  called  every  lime  th 
program  runs,  and  if  the  code  in  that  routine  is  not  modified 
during  execution,  the  program  is  probably  rcstartable. 

When  an  application  quits  with  a  ProDOS  16  QUIT  call  {descri 
next),  it  tells  its  controlling  program  whether  it  (the  appHcationi 
is  restariablc  or  not,  Cfhe  controlling  program  simply  lakes  the 
application's  word  for  this,  by  the  way.)  If  the  application  says  it, 
wants  to  be  restarted  and  claims  to  be  restariable,  the  contfoUt 
program  makes  it  dormant.  If  the  application  says  it  is  not 
restartable,  tlie  controlling  program  removes  all  of  its  segments 
from  memory. 

4"  Noie:  It  is  difficult  to  make  some  programs  in  some  languag 
restariable;  they  require  initialization  information  to  be  load 
from  disk  every  time  ihey  execute.  To  help  in  such  cases,  the 
System  Loader  supports  RELOAD  segments.  If  all  iniiializailo 
information  is  put  into  a  RELOAD  segment,  a  program  thai 
could  not  otherwise  be  restarted  can  make  itself  resiartable. 
When  a  program  is  restarted  from  a  dormant  state,  only  its 
RELOAD  segments  (plus  any  initialization  segments)  are  read 
from  disk. 


Quitting  and  launching  under  ProDOS  16 

ProDOS  1 6  and  the  System  Loader  provide  a  sophisticated 
method  for  passing  control  among  different  applications. 
Through  the  ProDOS  l6  QUIT  call,  an  application  can  do  one  i 
tJiree  things: 

□  Quit  permanently. 
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D  Quit  permanemly,  but  tell  ProDOS  l6  lo  launch  another 

specified  application, 
□  Quit  to  a  specified  application  temporarily,  telling  ProDOS  l6 

it  wants  to  be  re-executed  after  the  specified  application  quits. 

When  tt  launches  another  application  or  quits  temporarily 
through  the  QUIT  call,  an  application  is  not  functioning  as  a 
controlling  program.  It  is  not  maintained  in  memory  (except, 
possibly,  in  a  dormant  state)  while  the  other  program  executes.  A 
finder  or  program  launcher,  for  example,  is  an  application  that 
quits  temporarily  each  time  an  application  is  launched,  returning 
after  the  application  quits,  U  is  not  a  shell. 

❖  Nate:  If  you  are  writing  a  typical  application  in  a  high-level  lan- 
guage, you  may  not  need  any  of  the  information  here — your 
compiler  determines  the  manner  in  which  your  program  quits. 
If  you  are  writing  a  typical  applicaition  in  assscmbly  language,  be 
sure  to  read  the  "Hodge Podge"  note  at  the  end  of  this  seaion. 


Quitting,  launching,  and  returning 

Calling  QUIT  terminates  the  present  application.  It  also  closes  all 
lie  sysfem  file  level  is  described        open  files,  sets  the  current  system  Jile  level  to  zero,  and 
later  In  this  chapter,  under  -The  deallocates  any  installed  interrupt  handlers.  ProDOS  l6  can  then 

RroDOS  File  System  , - 

□  launch  a  file  specified  by  the  quitting  program 

□  automatically  launch  a  program  specified  in  the  quit  return 
stack 

The  quit  return  stack  is  a  table  of  User  ID'S  maintained  in  memory 
by  ProDOS  16.  It  provides  a  convenient  means  for  a  program  to 
function  like  a  shell — the  program  can  pass  execution  to 
subsidiary  programs  (even  other  shell-like  applications),  while 
ensuring  that  control  eventually  returns  to  it. 

For  example,  a  program  selector  may  push  its  User  ID  onto  the 
quit  return  stack  whenever  it  launches  an  application  (by  making  a 
QUIT  call).  That  program  may  or  may  not  specify  yet  another 
program  when  it  quits,  and  it  may  or  may  not  push  its  own  User 
ID  onto  the  quit  return  stack.  Eventually,  however,  when  no  more 
programs  have  been  specified  and  no  others  are  waiting  for 
control  to  return  lo  them,  the  program  selector's  User  ID  will  be 
pulled  from  the  stack  and  it  will  be  executed  once  again. 

When  your  application  makes  3  QUIT  call,  it  specifies  these  two 
parameters: 


Quitting  and  Eaurchlng  urtder  ProDOS  16 
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The  exact  formot  of  the  flag  word, 
ond  the  rest  of  ifhe  Pro  DOS  16  QUtT 
call,  is  given  in  the  App\e  Hs$ 
PtoDOS  )6  Reference. 


Using  the  PtoOOS  3  QUIT  coil  on  the 
App'e  lIGS  is  discussed  In  the 
Apple  lies  ProDOS  }d  Referenca 


1.  Palhname  pointer — if  .specified,  it  indicates  the  program  to  be 
loaded  and  executed.  If  no  pathname  is  specified,  ProDOS  l6 
pulls  a  User  ]D  from  the  quit  return  stack  and  executes  the 
program  with  that  User  ID. 

Z  Flag  word — it  contains  two  boolean  values.-  a  return  Jlag mdi 
restart -from-rnemory  flag  The  return  flag  tells  ProDOS  l6 
whether  the  program  making  the  QUIT  call  wants  to  retjrn;  if 
so,  its  User  ID  is  pushed  onto  the  quit  return  stack.  The  restart- 
from-memory  flag  tells  ProDOS  16  whether  the  quitting 
program  in  resiartable.  If  it  is  not,  the  program  must  be 
reloaded  from  disk  the  next  time  it  is  run,  The  information 
from  t}iis  Hag  is  saved  on  the  quit  return  stack  along  with  the 
User  ID. 

'^  ProDOS  8-  This  automatic  return  mechanism  is  specific  to  the 
ProDOS  16  QUIT  call,  and  therefore  is  not  available  to  ProDOS 
8  programs  on  the  Apple  llGS.  When  a  ProDOS  &  application 
quits,  it  can  pass  control  to  another  program  but  it  cannot  pi 
its  own  ID  on  the  quit  return  stack. 

How  a  particular  application  quits  is  language-specific.  Far 
example,  C  programs  terminate  with  a  left -facing  bracket,  and 
Pascal  programs  end  with  an  END  ,  statement.  In  either  case  theie 
is  no  way  to  make  an  explicit  QUIT  statement.  The  actual  quit 
statement  is  inserted  when  the  program  is  compiled.  Assembly- 
language  programs,  however,  make  explicit  QUIT  calls. 

*  HodgePodge:  'Ihe  assembly-language  version  of  HodgePo 
has  the  followingProDOS  l6  (macro)  QUIT  statement: 

Quit  QuitParams 

where  the  _Quit  macro  translates  directly  into  a  ProDOSt 
QUIT  call,  and  the  QuitFarams  parameter  list  consists  of  I 
null  bytes  (corresponding  to  a  null  pathname  pointer), 
followed  by  a  word- length  flag  value  of  $4000  (meaning  thai 
Hodgepodge  is  restartable  from  memory). 


Setting  up  direct-page/stack  space 

For  assembly-language  programmers,  the  65C816  processor 
provides  the  convenience  of  a  direct  page.  Accessing  and 
indexing  from  direct-page  addresses  are  efficient  because  add 
operands  are  a  single  byte,  rather  than  the  three  bytes  rec 
for  a  full  address  on  the  65C816. 
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For  all  programmers,  direct  page  is  of  interest  because  sev 
Apple  1IG5  tool  sets  require  thai  the  application  provide  d 
page  space  for  them. 

The  size  and  location  of  the  stack  may  also  be  of  parUcuIa 
interest  to  you  if  you  are  writing  heavily  recursive  rouUnes 
require  large  stack  space. 


Sondard-ApplQ  II  stock  and  zsio 
poge  are  discussed  !n  Apple 
It  Technical  Reference  Manual 
irdtheAppfe  tie  Technical 
liBlaencB  Manual 


How  direct  page  and  stack  ar©  organized 

In  the  Apple  IIGS.  the  65C8l6  microprocessor's  stack  pointer 
register  is  \6  bits  wide;  that  means  that  the  hardware  stack  may  be 
located  atiyi^'here  in  bank  SOO  of  memory.  Also,  the  stack  may  be 
as  much  as  6AK  deep,  In  theory,  then,  the  stack  may  occupy  any 
unused  space  of  any  size  in  bank  $00. 

The  direct  page  is  the  Apple  IIGS  equivalent  to  the  zero  page  on 
a  standard  Apple  11  computer.  The  difference  is  that  it  need  not 
be  page  zero  in  memory.  Like  the  stack,  the  direct  page  may  be 
placed  in  any  unused  area  of  bank  $00.  The  microprocessor's 
direct  register  (D  register)  is  l6  bits  wide,  and  all  zero-page 
(direct-page)  addresses  are  added  as  offsets  to  the  contents  of 
that  register.  Because  the  direct  page  can  be  located  anywhere  in 
bank  SOO,  you  can  allocate  more  than  256  bytes  (that  is,  more 
than  one  page)  as  direct-page  space  for  your  program.  Then,  by 
changing  the  value  of  the  D  register  while  the  program  is  mnmng. 
you  can  use  direct  addressing  to  access  any  poruon  of  the  direct 
page  space. 

In  principle,  the  endre  64K  of  bank  $00  could  be  used  for  the 
combined  direct-page/stack  space.  In  practice,  however,  less  space 
is  available.  First,  only  the  lower  48K  of  bank  $00  can  be  allocated; 
the  rest  is  reserved  for  T/O  and  system  software.  Also,  because 
more  than  one  program  can  be  in  memory  at  a  time,  there  may 
be  more  than  one  stack  and  more  than  one  direct  page  in  bank 
SOO.  Furthermore,  many  applications  may  have  parts  of  their  code 
as  well  as  their  stacks  and  direct  pages  in  bank  $00. 
Your  program  should  therefore  be  as  efficient  as  possible  in  its 
use  of  direct-page/stack  space.  The  total  size  of  both  should 
probably  not  exceed  about  4K  in  most  cases.  Still,  with  a  space 
that  size  you  can  write  programs  that  require  stacks  and  direct- 
page  space  much  larger  than  the  512  bytes  available  on  standard 
Apple  II  computers. 


Setting  up  dlrect-page/stack  space 


❖  Note:  By  convention,  ihe  direct  page  and  stack  occupy  a  single 
memory  block  in  bank  $00,  Direct-page  addresses  are  pcsitiv? 
oiTsets  from  the  base  of  the  allocated  space,  and  the  staclt  grtw 
downward  from  the  top  of  the  space. 


Creating  a  direct- page/stack  segment 

Only  you  can  determine  how  much  stack  and  direct-page  space 
your  program  will  need  when  it  is  nannirrg.  The  best  time  lo  mste 
that  dctcrminaiJon  is  during  program  development,  when  you 
create  your  source  files.  There  are  three  ways  to  allocate  (he 
direct-page/stack  space  you  need: 

□  Define  it  as  a  program  segment. 

□  Use  the  ProDOS  16  defaull. 

□  Create  it  at  run  time. 

Define  it  as  a  program  segment 

You  can  specify  the  size  and  contents  of  your  program's  . 
direct-page  space  by  creating  a  dircct-page/stack  segment ' 
you  assemble  Cor  compile)  and  link  your  program.  The  siffi  * 
segment  is  the  total  amount  of  stack  and  direct-page  space 
allocated  to  your  program,  and  the  contents  of  the  segment : 
whatever  initial  contents  you  want  the  direcl-page/stack  space  j 
to  have. 

Each  time  a  program  is  started,  the  System  Loader  looks  for  a 
direct-page/stack  segment.  If  it  finds  one,  it  loads  the  segmeiiu 
passes  its  base  address  and  size  to  ProDOS  l6,  along  with  the 
program's  User  ID  and  starting  address.  ProDOS  I6  sc\s  \htk\ 
(accumulator),  D  (direct),  and  S  (stack)  registers  as  shown  I 
then  passes  control  to  the  program. 


R«gtfter 


Contents 


A 
D 


User  ID  assigned  to  the  program 

address  of  the  first  (lowest)  byte  in  the  dircct- 
page/siack  space 

address  of  the  last  (highest)  byte  in  the  direct- 
page/stack  space 
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W&d  is  descfibed  in  the  Apple 
DSS  Ptcgrammer's  Workshop 
fiflferenca  An  example  of  a 
UnkEct  file  Is  shown  in  "Creating 
tegmented  Code.  Ttiree 
EKjmples'  in  Chapter  7. 


KIND  Is  a  segment-description 
feid.  See  "Oblect  Module 
Format'  In  the  Appls  t!GS 
Ptagrammer's  WorSc^op 
teterenceor  "Systsm  LoodDf 
Teciinlcol  Data'  In  the  Apple  HQS 
F^oDOS  J6  Hefermce. 

1. 

Cfeale  an 
object  segment 
of  proper  size- 
Obi^ct  file: 


To  specify  ihe  dircct-page/stack  space  for  your  program  use  Oje 
following  procedure  (in  APW  assembly  language,  using  LinkEdJ. 
See  also  Figure  6-5. 

1  Create  a  dau  segment  in  your  source  Be  wiih  the  size  and 
conients  you  want  for  your  iniiial  direct  page  and  stack. 

2.  Assemble  the  program. 

3,  use  a  LinkEd  file  to  link  the  program.  Make  the  direct- 
page/stack  segment  a  load  segment  by  itself,  with  KIND=S0812 
(meaning  il  is  a  static,  absolute-bank,  direct- page/stack 
segment). 


Place  it  In  a  single 
direct-poge/stack 
lood  segment. 

Load  ril?: 


1 


Segment  1 


Segment  2 


Segment  l 


The  Syitem 
Loader 
loads  It 
into 
Banl< 

soo. 


ProDOS  \6  sets  tl^e 
stack  reQlste'  to 

the  highest  address 
in  the  segment. 


Linkat 


Segment  n 


loader 


Dirsct  page 
and  stock 


ProDOS  16  sets  the 
direct  register 
to  the  lowest 

oddress  in 
ttie  segment. 


Figure  6*5 

Loading  a  direct- page/stack  segment 


Setting  up  direct-page /stack  space 
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Use  the  ProDOS  16  default 


See  theAppJe  ms  Toolbox 
Reference  for  a  generol 
dBscrlption  of  memofv  block 
aflrlbutos  assigned  by  the 
Memory  Manager, 


HocJgePodge's  dlrecf-poge 
allocation  lor  tool  sets  Is 
demonstrated  under  "Start  the 
Program'  ir\  Chopter  2. 


I 


If  Ihe  Ictadcr  finds  no  direct-page/stack  segment  in  a  file  at  load 
time,  ProDOS  16  itself  calls  the  Memory  Manager  to  allocate  a 
default  direct'page/stack  segment,  in  a  memorjr  block  with  these 
attributes;  Hi 

Size 
Owner 

Fixed/movable 
Lock  ed/u  nl  ocked 
Purge  level 

May  cross  bank  boundary? 
May  use  special  memory? 
Alignment 

Absolute  starting  address? 
Fixed  bank? 


1,024  bytes 

program  with  the  User  ID 
returned  by  Ihe  loader 
fixed 
locked 
1 

no 
yes 

page-aligned 
no 

yes — bank  $00 


Once  allocated,  the  default  direct-page/siack  space  is  treated  just 
as  it  would  be  if  ii  had  been  specified  by  the  program:  ProDOS  16 
sets  the  A.  D,  and  S  registers  before  handing  control  to  the 
program,  and  at  shutdown  the  System  Loader  makes  the  segment 
purgeable. 

For  many  assembly-language  applications,  the  IK  default  stack 
and  direct  page  space  allocated  by  ProDOS  16  are  sufficient. 
Individual  high-level  language  systems  may  have  the  same  or 
different  default  sii^es;  check  your  language  reference  manual. 

❖  Hodgepodge:  Hodgepodge  accepts  the  default  direct- 
page/stack  space  set  up  for  it  by  ProDOS  16.  In  addition,  it 
manually  creates  a  direct-page  space  for  tool  sets,  by  a  method 
similar  to  that  described  next,  under  "Create  It  ai  Run  Time. 


Creole  it  at  run  Kme 


I 


If  the  ProDOS  l6  default  space  is  the  wrong  size  for  your  applica- 
tion, and  if  for  some  reason  you  do  not  want  to  specify  the  size  of 
your  direct-page/stack  space  at  link  time,  you  can  include  ProDOS 
16  and  Memory  Manager  calls  in  your  program  that  allocate  a 
direct-page/stack  space  during  program  execution.  In  that  case, 
when  ProDOS  l6  transfers  control  to  your  program,  save  the  User 
ID  value  left  in  she  accumulator  Cor  use  the  User  ID  returned  by 
the  Memory  Manager  startup  call)  before  doing  the  foilowingt 
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1  Using  the  starting  or  ending  address  left  in  the  D  or  S  register 
by  ProDOS  l6,  make  a  TindKandle  call  to  the  Memory 
Manager  to  geE  the  memory  handle  of  Ihe  automatically 
provided  direct-pagc/ssack  space.  Then,  using  that  handle,  get 
rid  of  the  space  with  a  Disposer landle  call. 

2.  You,  can  now  allocate  your  own  direct- page/stack  space  through 
the  Memory  Manager  NewHandle  call.  Make  sure  that  llie 
allocated,  block  is  purgeable,  unmovable,  and  locked. 

3.  Place  the  appropriate  values  tbeginning  and  ending  addresses 
of  the  segment)  in  the  D  and  S  registers. 


Cautions 

When  your  program  terminates  with  a  QUIT  call,  the  System 
Loader  makes  the  dircct-page/stack  segment  purgeable,  along  with 
the  program's  other  static  segments.  Bank  SOO  is  heavily  used,  and 
if  the  direct-pagc/stack  segment  is  purged,  your  entire  program 
will  have  to  be  reloaded  from  disk  when  it  reejtecutes. 

If  your  direct-page/stack  load  segment  contains  initialisation  data, 
you  need  to  make  it  a  RELOAD  segment  if  you  want  your  program 
to  be  restartable. 

There  is  no  provision  for  extending  or  moving  the  direct- 
page/stack  space  after  its  initial  allocation.  Because  bank  $00  is  so 
heavily  used,  the  space  you  request  may  be  unavailable— the 
memory  adjoining  your  stack  is  likely  to  be  occupied  by  a  locked 
memory  block.  Make  sure  that  the  amount  of  space  you  specify  at 
link  time  fills  all  your  program's  needs. 


Important    The  Apple  liGS  provides  no  mechanism  for  detecting  stack 

underflow  or  overflow  (collision  of  Itie  stack  with  the  direct  page). 
Your  program  must  be  carefully  designed  and  tested  to  mai<©  sure 
this  cannot  occur. 


Hie  tGfm  PtoDOS  (as  In  ProDOS  file 
system)  refers  to  features 
common  1o  both  PtoDOS  8  and 
ProDOS  16.  The  term  PtoDOS  16ias 
h  ProDOS  J6  pfeflxBS )  \s  used  to 
describe  features  thot  PtoDOS  B 
do«  not  have. 


I 


The  ProDOS  file  system 

You  use  the  Apple  IIGS  disk  operating  system,  ProDOS  l6,  to 
open,  close,  create,  delete,  and  otherwise  manipulate  files  on  disk. 
This  section  describes  the  filename  and  prefix  conventions  used 
by  ProDOS  l6  and  introduces  some  of  the  ProDOS  l6  functions 
that  your  program  may  call. 


The  PfoDOS  file  system 
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Filenames  and  pafhnomes 


directory.      ^^'"^'^  ^  '^''^'^^"^^  "^"st  be  unique  within  to 


IshT/T^fe  n^ren/  ■  e.ch  preceded  b 

-1 


Pathname  prefixes 

volume  name  The  ma^im,,^  i  u  ^  ^""^  '^'^^^^  ^  ^'^^'^'^e 
characters,  .^ci^^^^Zt^r  """^  ''^^  ^  ^^^'^^  ^^^^-^ 

more  lhan  one  Drefi.  ,  FroDOS  16  allows  you  to  define 

F  <iie    irom  ihe  partial  pathname,  men  Pmno*;  i< 
prefixes  are  as  follovw,  '  predefined 


Choptsr  a  Momory.  Segments,  and  Ftes 


See  the  ProDOS  3  Technical 
Reterence  Manual  fat  more 
Information  on  PioDOS  8  preflu 
corventlons, 


Table  A-2 

Examples  of  prefix  use 
Ca»  Illustrated 


♦  /         Boot  prefix:  Ihe  name  of  the  volume  from  which  the 
presently  running  ProDOS  l6  was  booted, 

0/  Default  prefix:  (automaUcally  attached  to  any  partial 

pathname  that  has  no  prefix  number)— it  has  a  value 
dependent  on  how  the  current  program  was  launched  In 
most  cases  the  default  prefix  is  equal  to  the  boot  prefix, 

1/  Application  prefix-,  the  pathname  of  the  subdirectory 

that  contains  the  currently  running  application. 

2/  System  library  prefix:  the  pathname  of  the  subdirectory- 

Con  the  boot  volume)  that  contains  the  library  files  used 
by  applications. 

3/_7/    NuU  strings:  (unless  previously  defined  by  an  application). 
Your  application  roay  change  the  values  of  all  prefixes  except 
prefix  */. 

Prefix  0/  the  default  prefix,  is  similar  to  the  ProDOS  8  system 
prefix  in'ihat  ProDOS  l6  automatically  attaches  prefix  0/  to  any 
partial  pathname  for  which  you  specify  no  prefix.  However,  its 
initial  value  is  not  always  equivalent  to  the  ProDOS  8  system 
prefix's  initial  value. 

The  maximum  length  for  a  pr^:fix  is  64  characters.  The  minimum 
length  for  a  prefix  is  zero  characters;  a  prefix  of  zero  length  is 
known  as  a  nuU  prefix.  You  set  and  read  prefixes  using  the  calls 
SET_PREFIX  and  GET_PREFIX.  The  54-character  limits  for  the 
prefix  and  partial  pathname  combine  to  create  a  maximum 
effective  paLhname  length  of  128  characters. 
Table  6-2  shows  some  examples  of  prefix  use.  The  pathname 
provided  by  the  caller  is  compared  with  the  full  pathname 
constnicted  by  ProDOS  l6.  The  examples  assume  that  prefix  0/  is 
/voLUMBi/  and  prefix  5/  is  /  volume  1/ text  .files/ 


Pathname  provldad 


Pathname  m  expanded 


Full  pathname  /volumei/text . files/chap . 3    /volumei /text, files /chap .3 

ImpUcit  use  of  prefix  0/     TEXT  .FILES/ CHAP  .  3  / VOLUME  1 /TEXT. FILES/ CHAP  .  3 

ExpliCituse  of  prefix  0/      0 /TEXT  .FILES /CHAP  .  3  /  VOLUME  1/ TEXT  .  FILES /CHAP  .  3 

Use  of  prefix  5 /  5/CHAP  .  3  /VOLUMEl /TEXT  .FILES/CHAP .  3 

Note:  Thess  examples  assume  that  prefix  0/  is  set  to  /VOLUME  1/  and  that  prefix  5  /  is  set  to 

/VOLUMEl/TEXT.  FILES/. 
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tmpoftant    When  your  appflcQtion  is  bunched,  oil  nine  prefix  numbers  are 

dssigned  to  specific  pathnames  Csome  are  meanlngfuf  pathrtar,,^ 
and  omers  may  be  null  strings).  However,  prefixes  o  /  and  2/  may 
nof  have  the  expected  ProDOS  16  default  vofues- they  may 
reflect  changes  made  by  the  prevloiB  application.  Bev^ore  of 
assuming  any  particular  initial  value  for  any  particular  prefix, 


All  of  thesa  file  attributes  or©  fufly 
explained  In  Appendix  A  of  the 
Appiell&s  ProDOS  JdR&ferancB 


Creating  and  destroying  fifes 

A  file  is  placed  on  a  di.?i^  by  the  ProDOS  16  CREATE  call.  When  ■ 
you  create  a  file,  you  assign  it  several  properties,  including 

□  pathname 

□  access  attributes  (deleuble,  renamable,  wriieable,  readable, 
backup-required) 

□  file  type 

□  auxiliary  type 

□  creation  date  and  creation  time 

Once  a  file  has  been  created,  it  remains  on  the  disk  until  it  is 
deleted  (by  using  the  DESTROY  call). 


Opening,  closing,  and  flushing  fifes 

Before  you  can  read  information  from  or  write  Informaiiion  to  a 
nie,  you  must  use  the  ProDOS  l6  OPEN  call  to  open  the  file  for 
access.  The  OPEN  call  returns  a  reference  number  for  the  file.  All 
subsequent  references  to  the  open  file  must  use  its  reference 
number.  The  file  remains  open  until  you  use  the  CLOSE  call  onit  j 

When  you  finish  reading  from  or  writing  to  a  file,  you  must  use 
CLOSE  call  to  close  [he  file,  CLOSE  writes  any  unwritten  data  frgn 
the  file's  I/O  buffer  to  the  file,  and  it  updates  the  file's  size  in  the 
directory  if  necessary.  To  access  the  file  again,  you  have  to 
reopen  ft. 

FLUSH,  like  CLOSE,  writes  any  unwritten  data  from  the  File's  UO 
bulTer  to  the  file,  and  updates  the  file's  size  in  the  directory. 
However,  FLUSH  keeps  the  file  open. 
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File  levels 

When  a  Hie  is  opened,  it  is  assigned  a  file  level  according  to  che 
system  file  leveL  You  can  determine  the  current  system  file  level 
with  a  GET_LEVEL  call,  and  can  change  the  level  with  a 
SET_LEVEL  call-  When  you  specify  0  as  the  reference  number  in 
ihe  CLOSE  and  FLUSH  calls,  all  files  having  a  File  level  greater 
than  or  equal  to  the  current  system  Tile  level  are  closed  or  flushed. 

This  feature  allows  controlling  programs  to  quickly  dose  all  files 
associated  with  their  subprograms.  For  example,  when  a  shell 
program  takes  control  of  the  Apple  IICS,  i:  can  execute  a 
GET_LEVEL  call  to  determine  the  current  system  file  level,  then 
execute  a  SET_LEVEL  call  to  set  the  system  file  level  to  a  higher 
level.  Each  file  opened  by  the  shell  and  by  the  programs  that  run 
under  the  shell  is  then  assigned  the  new  file  level  by  ProDOS  16. 

When  the  shell  is  ready  to  quit,  it  can  execute  a  CLOSE  call  with  a 
reference  number  of  0,  and  all  files  opened  under  the  shell  (that 
is,  those  with  a  file  level  equal  to  or  greater  than  the  current 
system  file  level)  are  closed,  The  shell  can  then  execute  a 
SET_LEVEL  call  to  return  the  system  file  level  to  its  previous  value, 
and  finally  execute  a  QUIT  call. 


Reading  and  writing  files 

READ  and  WKITE  calls  to  ProDOS  l6  transfer  data  between 
memory  and  a  file.  For  both  calls,  the  application  must  specify 
the  locadon  in  memory  of  a  buffer  that  contains,  or  is  to  contain, 
the  transferred  data.  When  the  request  has  been  carried  out, 
ProDOS  16  passes  back  to  the  application  the  number  of  bytes 
thai  it  actually  transferred. 

A  read  or  write  request  starts  at  a  specific  position  in  the  file,  and 
continues  until  the  requested  number  of  bytes  has  been 
transferred  (or,  on  a  read,  until  the  end-of-file  has  been  reached). 
Read  requests  can  also  terminate  when  a  specified  character  (the 
newline  character  set  by  the  NEWUNE  call)  is  read, 
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LoodOnelaln  the  source  file  The  HodgePodge  routine  that  reads  files  is  LoadOne,  called  fro 

PAINT.PAS.  jfig  routine  AskUser,  which  itself  is  called  from  DoTheOpen 

the  user  wants  to  open  a  pic w re  window.  ijoadOne  makes  th 
ProDOS  16  calls  OPEN,  READ,  and  CLOSE; 


function  LoadOne:  Boolean; 
var 


openBlk 
readBlk 


OpenRec; 
FilelQRec; 


LoadOne  FALSE 
NaitCuraor ; 

pictHndl  :=  Hav#Haa%dl«»  ($8000, 

0, 

Ptr(O) ); 

if  isTcxalErTOr  then 
Exit,* 

BCiCicJc  (pictHndl )  ; 

openBlk. openPathname  :» 

^jnyReply .  f  ullPathnamfi; 
openBlk.ioBuffer  NIL; 

OPEH (openBlk) ; 
if  CheckDiakError C27)  then 
Exit; 


readBlk . databuf f er 
readBlk . requeatCount 
readBlk . f lleRefNura 


pictHndl'"; 
$6000; 

op^nBik .operRefHum; 


mm  (readBlk)  ; 
if  CheckDiskErroi (28)  Chen 
Exit; 

CLOSE ( readBlk ) ; 
HDiiLocJc  (pictHndl)  ; 

LoadOne  TRtffi; 

end/ 


(begin  loadOne...} 

(ProDOS  16  parameter  blocks,.,) 
(^defined  in  ProDOS  16  interface) 


{Initialize  value  of  function) 
{put  up  watch  cursor) 
{request  metnory  to  hold  the  picture,,) 
(Hodgepodge's  User  ID) 
(not  purgeable,  no  restriotions} 
(anywhere) 

(If  the  ineniory  is  unavailable...) 
(..J.eave  thia  subroutine} 

(Lock  handle  so  picture  won't  move]] 
(Now  fill  in  parameter  block:...} 

{pathname  frorti  Std.  File  results_t 
{zero  this  paraitteter} 

{mak«  a  ProDOS  16  OPEN  call) 

(If  it  fails  for  some  reason...} 

(...display  error  and  exit) 

(Fill  in  parameter  block  for  READ:. 

(pointer  to  where  to  put  data) 

(requested  no.  of  bytes  to  read) 

(file's  reference  number) 

(make  a  ProDOS  16  I?EAD  call) 
(If  it  fails  for  some  reason,.,) 
(„, display  error  and  exit) 
(Open  file  no  longer  necessary :„.) 
(Make  a  ProDOS  16  CLOSE  call) 
(Unlock  the  handle  until  we.,.) 
(..Jieed  the  picture  again} 
(function  successfully  coLrpleted) 

{end  of  LoadOne} 
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no  Is  in  the  sourca  file 

UWT.PAS. 


The  HodgePodge  routine  that  creates  files  and  saves  them  to  disk 
is  SaveOne.  It  is  called  from  the  routine  DoSaveltem  (which 
saves  the  contents  of  a  picture  file  to  disk),  desaibed  under 
"Communicating  With  Files  and  Devices"  in  Chapter  5.  SaveOne 
makes  the  ProDOS  l6  calls  CREATE,  DESTROY,  OPEN,  >XTUTE, 
and  CLOSE; 


■OtXtSui%  SaveOne  (plct:  Handle)  ; 


destroyBlk 

openBlk 
utiteBlk 


PathnameRec; 
FileRec; 
OpenRec  ; 
FilelORec," 


{begn  SaveOne_.) 

{a  ProDOS  16  parameter  block} 
{a  ProDOS  16  parameter  block} 
{a  ProDOS  16  parameter  block} 
{a  ProDOS  16  parameter  block} 


dfliatroyBlk  -  pathname  :- 

gmyReply ,  f  ullPathnaine; 

DESTROY  (de  at  royBlk)  ; 

ccasiteBlk.  pathname 

GnryReply ,  fullPathname; 
createBlk.  fAcceas         :■  $C3; 
createBlk.fileType      :=  SCI; 
createBlk.auxType        :■  0; 
createBlk.storageType;'"  1; 
createlk.createDate  0; 
CteateBlk.createTime  0; 


(Put  pathname  from  DoSaveltem.,.} 
{».reply  record  into  param.  block} 

(Delete  any  existing  file  with 
that  pathname) 

(Put  the  pathnainB  in  the  block...} 
(...give  it  this  access  value„,) 
(...assign  a  file  type  (unpacked) „,) 
(..aux.  type  -  0...} 
(..juke  it  a  seedling  file...) 
(...let  ProDOS  16  assign...} 
(...creation  date  and  time.) 


CBEATE  (oreateBlk)  ; 

if  CheckDiflkEr ror  (25)  cijan 

openBlk .  openPat  hnajine  :  - 

gmyReply .  £ullPathnalne; 
openBlk.ioBuffer     :-  NIL; 


i Create  the  new  file} 

{If  the  file  can't  be  created^.} 

(^display  error  and  exit} 


(Put  the  pathname  into  the  block} 
{  (this  field  must  be  zero]  ) 


► OPESJ  (OpenBlk) ; 
writeBlk.dataBuffer  pict^; 
writcBllc.  request  Count  58000; 
HriteBlk.fileRefNum  openBlX- fileReENora; 

WRITE  (writeBlk) ; 
^   if  CheckDiskError  (26)  thaa 
U  Exit; 

CLOSE  (writeBlk) ; 


aid; 


(Open  the  file  we've  just  created} 
(Make  a  pointer  to  the  buffer,.,) 
(...from  the  handle  to  the  picture} 
(Transfer  the  entire  32K-byte  file) 
( supply  file's  re  f_num ) 
(Write  the  data  to  the  file} 
(If  the  file  can't  be  written  to...) 
{^.digplay  error  and  exit} 

{Close  the  file} 

{End  of  SaveOne} 
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Brief  expionotlons  of  csrtoin 
PfoDOS  16  parameters,  such  as 
occesj  and  file  type,  are  found 
elsewhere  In  this  section, 


For  more  fnformotlon  on  all  file 
attributes,  see  Appendix  A  of  tha 
Apple  IIGS  ProDOS  16  Reference 


The  parameter  lIsLs  for  the  ProDOS  16  calls  used  In  LoadOne 
Save  One  are  all  combined  into  the  single  record  Pl6Bllc, 
defined  in  the  Pascal  interface  library  to  ProDOS  16.  Complete 
documentation  of  required  parameters  for  all  ProDOS  l6  calls  is 
in  tlie  Apple  HGS  ProDOS  16  Reference. 

The  EOF  and  Mark 

To  aid  reading  from  and  writing  to  files,  each  open  file  has  one 
number  indicating  the  end  of  the  file  (the  EOF),  and  another 
defining  the  current  position  in  the  file  (the  Mark),  ProDOS  IS 
moves  (increments  or  decrements)  both  the  EOF  and  the  Mark 
automaUcally  when  necessary,  but  an  application  program  can 
also  manipulate  them  independently  of  ProDOS  16. 

The  EOF  is  the  number  of  readable  bytes  in  the  file.  The  Mark 
cannot  exceed  the  EOF.  If  during  a  write  operation  the  Mark  nm 
the  EOF,  both  the  Mark  and  the  EOF  are  moved  forward  one 
position  for  every  additional  byle  written  to  the  file. 

To  move  the  EOF  and  Mark,  use  the  SE'IIEOF  and  SET_MAftK 
calls.  To  determine  the  current  values  of  the  EOF  and  the  Mark, 
use  the  GET_EOJ-  and  GET_MARK  calls. 

❖  HodgePodga.  Hodgepodge  doesn't  pay  much  attention  to  EOF 
and  Mark  in  its  file  access,  because  it  reads  and  writes  only 
entire  files  at  a  time, 


File  attributes 

The  directory  entry  for  each  file  contains  information  that 
be  useful  to  your  program.  This  secUon  describes  the  follow!^ 
fields  in  directory  entries  and  headers: 

□  creation  and  last-modification  dates 

□  access  attributes 

□  file  type 

□  auxiliary  type 

If  you  want  to  know  the  properties  of  a  given  file,  use  the 
GET.FILE.FN'FO  call.  If  you  want  to  change  the  file's  name,  me  the  i 
CHAKGE_PATH  call.  To  alter  the  other  properties  use  the 
SET_FILEJNFO  call. 
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Creation  and  last -modification  date  and  time 

The  date  and  lime  of  creation  of  a  file  are  stored  in  the  file's 
directory  entry.  When  your  program  creates  a  new  file,  ProDOS  l6 
automatically  gives  the  file  the  current  system  date  and  lime. 
When  your  program  modifies  a  preexisting  file,  ProDOS  l6 
automatically  sets  the  last-modification  date  and  time  to  the 
current  date  and  time.  In  general,  your  program  should  not  have 
to  change  these  attributes. 

Access 

The  access  attribute  field,  or  access  byte,  determines  whether  the 
file  can  be  read  from,  written  to,  deleted,  or  renamed.  It  also 
contains  a  bit  that  can  be  used  to  indicate  whether  a  backup  copy 
of  the  file  has  been  made  since  the  file's  last  modification. 

ProDOS  16  sets  the  backup  bit  whenever  the  file  is  changed  (that 
is,  after  a  CREATE,  RENAME,  CLOSE  after  WRIl^,  or 
SET_FILE_INFO  operation).  This  bit  should  be  reset  by  a  backup 
utility  (using  CLEAB_BACKUP_BlT)  whenever  it  makes  a  backup 
copy  of  the  file.  No  other  program  should  ever  reset  the  backup 
bit. 

<•  Hodgepodge:  When  HodgePodge  creates  its  picture  files,  it 
assigns  them  the  access  value  of  SC3,  meaning  that  they  may 
be  destroyed,  renamed,  read  from,  and  written  to. 

File  type 

The  f  ile_type  field  in  a  directory  entry  identifies  the  type  of 
file  described  by  that  entry.  This  field  should  be  used  by 
applications  to  guarantee  file  compatibility  from  one  application 
to  the  next.  The  currently  defined  hexadecimal  values  of  this  byte 
are  listed  in  Table  6-3. 

Table  6-3  also  lists  the  3-character  mnemonic  file-type  codes  that 
might  appear  in  catalog  listings.  For  any  file  type  without  a 
specified  mnemonic  code,  most  catalog  programs  substitute  the 
hexadecimal  file  type  number. 

SdSisthe  operoting  system  for  ❖  SOS:  SOS  file  types  are  included  in  Table  6-3  because  SOS  and 

Apple  III  computer,  ProDOS  have  idenUcal  file  structures.  Each  may  read  the 

other's  files. 

❖  HodgePodge.  When  HodgePodge  creates  its  picture  files,  it 
assigns  them  the  file  type  $C1  (picture  file,  unpacked  format). 
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Tabre  6-3 

ProDOS  fite  types 


File  typa 


Code 


DAjcrlpMon 


$00 

$01 

$02  • 

$03  ♦ 

S04 

$05  * 

506 

S07  • 

$08 

309  * 

$0A  • 

$0D  • 
SOC  ♦ 
$0I>-3OE 
$0F 
SIO  • 
$11  • 
$12  • 
$13  • 
$14  • 
$15  • 

$i6-sia  • 

519 
$1A 
SIB 

$1C-SAF 

$B0 

$B1 

$n2 

SIi3 
$B4 
SB5 
$B6 
$B7 
$B8 
$B9 
SBA 


BAD 

PCD 

PTX 

TXT 

PDA 

BIN 

FNT 

FOT 

BA3 

DA3 

WPF 

SOS 

DIR 

RPD 

RPI 


ADB 
AWP 
ASP 

SRC 

OBJ 

LIB 

Sl6 

RTL 

EXE 

PJF 

TIP 

NDA 

CDA 

TOL 


Uncaiegorized  file  CSOS  and  ProDOS) 
Bad  block  Qle 
Pascal  code  file 
Pascal  text  file 

ASCII  text  file  (SOS  and  ProDOS) 
Pascal  data  file 

General  binary  file  (SOS  and  ProDOS  8) 
Font  file 

Graphics  screen  file 
Business  BASIC  program  file 
Business  BASIC  data  file 
Word  processor  file 
SOS  system  file 
SOS  reserved 

Directory  file  (SOS  and  ProDOS) 
RPS  data  file 
HPS  index  file 
AppleFile  discard  file 
AppIeFile  model  file 
AppleFile  report  format  file 
Screen  library  file 
SOS  reserved 

AppleWorks®  Data  Base  file 

AppleWorks  Word  Proc.  file 

AppleWorks  Spreadsheet  file 

Reserved 

APW  source  file 

APW  object  file 

APW  library  file 

ProDOS  l6  application  program  file 
A?W  run-lime  library  file 
ProDOS  16  shell  application  file 
ProDOS  1 6  permanent  imtlalization  file 
ProDOS  16  temporary  initialization  file 
New  desk  accessory 
Classic  desk  accessory 
Tool  seE  file 
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Table  (continued) 

ProDOS  file  types 

File  type 

Coda 

Descrlpllon 

—  

5BB 

ririvfr  flip 

SBC 

f^pnp™!  PrnnO'i  Ifi  Inarl  file 

SCO 

Apple  IIGS  picture  file  (packed  f Of  mats) 

SCI 

Apple  IIGS  picture  file  Cunpacked  format) 

SC2-SEE 

Reserved 

SEF 

PAS 

Pascal  area  on  a  pariilioned  disk 

SFO 

CMD 

ProDOS  8  CI  added  command  file 

SF1-$F8 

ProDOS  8  user-defined  files  1-8 

$F9 

ProDOS  8  reserved 

$FA 

INT 

Integer  BASIC  program  file 

$FB 

IVR 

Integer  BASIC  variable  file 

Sfc 

BAS 

Applesoft  program  file 

SFD 

VAR 

Applesoft  variables  file 

SFE 

HEL 

Relocatable  code  file  (EDASM) 

$FF 

SYS 

ProDOS  8  system  program  file 

'apply  lo  Apple  III  (SOS)  only 

Auxiliary  type 

Some  applications  use  another  field  in  a  file's  directory  entry,  the 
auxiUary  type  field  (aux  type),  to  store  additional  information 
not  specified  by  the  file  type.  Some  catalog  listings  may  display 
the  contents  of  this  field  under  the  heading  "Subtype." 

For  example,  APW  source  files  (file  type  $B0)  Include  a  language- 
type  designation  in  the  c»ux_type  field.  The  starting  address  for 
ProDOS  8  executable  binary  files  (file  type  S06)  may  be  in  the 
aux_type  field.  The  record  size  for  random-access  text  files  (file 
type  $04)  may  be  specified  in  the  auxiliary  type  field, 
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For  most  file  types,  ProDOS  l6  and  ProDOS  8  impose  no 
restrictions  (other  than  size)  on  the  content,  or  format  of  tlK 
auxrliary  type  field.  Individual  applicEdons  may  use  those  two 
bytes  to  store  any  useful  information. 

*  Hodgepodge.  When  HodgePodge  creates  its  picture  files  it 
assigns  them  an  auxiliary  type  value  of  0.  It  stores  no  ' 
inlormaiion  in  the  auxiliary  type  field. 


SFG&tFlle  sends  to  OpenRlter  only 
m©  fits  types  specified  In  Its 
type  List  para  met  erases 
"Communicoffng  With  Files  and 
Devices"  in  Choptef  5. 


OpenFllter  Is  in  the  soutce  fife 
PAINT.  PAS. 


Controlling  user  accessloTiies 

"^L^cTn  '^'"^  ^""^  ''^'"'^  Hodgepodge  are  ProDOS 
ype  SCI  Because  HodgePodge  cannot  handle  other  file  types 
mc  user  should  not  be  permitted  to  select  anything  but  $C1  ffl 

select,  other  Ales  in  a  directo^>^ 

The  Hodgepodge  routine  OpenFilter  is  called  by  the  Stan 
Fjle  Operauons  Tool  Set  to  find  out  how  to  display  files  of 
%^;\L"  ^"^^  ,^Pf d^^J^S  box.  For  each  file  ent^  i:  encount. 
SFGetFile  calls  this  routine.  If  the  rouUne  returns  0.  the  filen. 
not  displayed;  if  the  routine  returns  1,  the  filename  appears" 

nienan^e  IS  not  dimmed  and  the  file  is  selectable.  OpenFilt« 
dims  all  file  types  but  SCI.  C"' 

tl^e  variable  FileTypePtr  below  is  a  pointer  to  the  file-typc 
field  ,n  the  directory  entry  for  the  file  under  consideration^ 
nie-type  field  is  at  an  offset  of  10  bytes  into  the  file  entry 


funr^io.  Op«nFUt«rfdi.E«try:longint):  integer; 
type      BytePtr         =  "byte; 
var       fileTypePtr  :  BytePtr; 
i>egin 

fUelVpePtr  :=  Pointer  (dirEntry  +  510;  • 
Ji™f^^^^^W^t^^$OOFF)  i  then 


OpenFilter 
eJse 

OpenFilter 
end/ 


1; 


{begin  OpenFilter..,} 


iFirat,  get  a  pointer  to  the  file*,  1 
file  type  from  its  directory  entry.} 
llf  It -a  unpacked  Picture  File  type.} 
(..jiHke  it  black  and  selectable) 
{If  Ifg  any  c5ther  file  type...) 
(...It's  dimmed  and  nonaelectablel 
{End  of  OpenFilter} 
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and  load  nic;-S^X  ^Sf:"^  "'^^T  '^'^^^ 

-    t;;:;x;!;r  d  S;'^  ^^^^ 
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Apple  NGS  Programmer's  Wo'rksh^^  " 

J  he  Apple  Ik:;3  Prograrnmer's  Workshon  fAPV^^n  ■ 
-dude.  ^  fnilcwi^g"  .^plt^^'^^'^  '"^^  "-^"^P-^- 

^P-ate  ...n^;^  InS^        <^nv:ronnr«en,:.  d...nb.d  ir, 
^  assejnblejT 
□  C  Compiicr 
D  "Lher  compijefs 

n  debuijiBicrs 


Program  descriptions 


The  programs  included  in  the  Apple  IIC5  Programmer's 
Workshop  relate  to  each  other  as  illustrated  in  Figure  7-1.  The 
APW  Shell's  command  interpreter  serves  as  the  interface  between 
you  and  the  rest  of  the  Apple  lIGS  system.  The  shell  allows  you  to 
call  the  other  programs  that  constitute  the  Apple  liGS 
Programmer's  Workshop,  and  serves  as  the  link  between  APW  and 
the  Apple  II GS  Toolbox  and  operating  system.  The  toolbox  and 
operating  system  (including  ProDOS  l6,  the  System  Loader,  and 
the  Memory  Manager)  are  the  interface  between  APW  and  Apple 
IIGS  hardware  and  firmware. 


Figure  7-1 

APW  programs  in  the  Apple  lies  system 


Shell 

The  shell  program  is  die  interface  that  allows  you  to  execute  APW 
commands  and  programs.  With  ii  you  can  perform  a  variety  of 
housekeeping  functions,  such  as  copying  and  deleting  files  or 
listing  a  directory.  The  shell  supports  input  and  output  redirection 
and  pipelining  of  APW  programs. 
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ProDOS  16  calls  are  descrfbsd  In 
fri©  Apple  lIGS  ProDOS  16 
Reference 


The  shell  ako  acts  as  an  interface  and  extension  to  ProDOS  l6 
providing  several  functions,  called  sheU  calls,  that  can  be  ailed 
by  programs  running  under  the  shell.  Shell  calls  can  be  used  by 
utility  programs,  compilers,  linkers,  or  assemblers  to  perform  iiudt 
functions  as  passing  parameters  and  operations  Hags  between  tlB 
shell  and  APW  programs.  The  format  for  making  diese  calls  is 
exactly  like  that  used  for  making  a  ProDOS  16  call. 

Editor 

Tliis  full  screen  text  editor  is  designed  for  use  with  APW 
assemblers  and  compilers.  It  allows  you  to  enter,  copy,  delete,  and 
move  text,  and  provides  automaQc  search  and  search-and-rep!i« 
functions. 


Macros  oro  commands,  each 
one  of  which  replaces  several 
Qssembly-languag©  Instructions 
or  assembler  directiv&$.  When  a 
progrgnn.  Is  assembled,  the 
assembler  i-eploces  macros  with 
their  equivalent  instructions  and 
directives. 


Assembler 

This  full-featured  assembler  allows  users  to  write  65816  assembij-- 
language  programs  for  the  Apple  IlGS  computer,  with  complete 
support  for  d:e  standard  Apple  lies  Hie  format  and  library  files 
The  Apple  IJGS  Programmer'sWorkshop  Assembler  includes 
macros  to  facilitate  assembly-language  programming,  and  allows 
usei^  to  write  their  own  macros  and  library  files. 

The  APW  Assembler  is  specifically  designed  for  writing  reloatiUle 
code,  because  the  APW  Linker,  System  Loader,  and  Memory  Mamj, 
are  all  designed  to  work  most  efficiently  with  relocatable  code 


C  CoFTtpiier 

The  Apple  IICS  Programmer's  Workshop  C  Compiler  is  a 
complete  implementation  of  the  C  programming  language  It 
consists  of  a  C  compiler,  the  Standard  C  Library,  the  Apple  HGS 
Interface  Libraries,  and  the  C  SANE  Library.  The  object  files 
output  by  the  C  compiler  are  fully  compatible  with  those  output 
by  the  APW  Assembler  and  consist  of  relocatable  code. 

Linker 

The  APW  Linker  takes  the  files  (called  object  Jiles)  created  by  the 
APW  Assembler  or  any  of  the  APW  compilers,  and  generates  files 
that  the  System  Loader  can  load  into  memory  Goad  Hies)  Iht  li ' 
resolves  external  references  and  creates  relocation  dictionaries 
which  allow  the  System  Loader  to  relocate  code  at  load  time  ' 
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Although  the  APW  Linker  is  a  single  program,  conceptually  there 
are  two  APW  linkers: 

O  Normally,  the  linker  is  called  directly  by  a  shell  cornmand 
(such  as  the  ASML  command,  which  assembles  and  links  a 
program),  These  commands  provide  a  limited  number  of 
linker  options;  most  linker  options  either  are  not  available  or 
are  set  to  default  values.  In  this  manual,  this  aspect  of  the  linker 
is  referred  to  as  the  standard  linker. 

□  Alternatively,  all  functions  of  the  APW  Linker  can  be  controlled 
by  compiling  a  file  of  linker  commands.  The  linker  command 
language,  called  LinkEd,  allows  you  to  do  such  things  as  place 
specific  object-file  segments  in  specific  load-file  segments, 
create  dynamic  load  segments,  set  load  addresses  for 
nonrelocatable  code,  search  libraries,  and  control  the  output 
printed  by  the  linker.  You  can  compile  and  execute  LinkEd 
commands  separately  from  your  source  code  by  using  the 
ASSEMBLE,  COJVlPlLE,  or  ALINK  commands  of  the  APW  Shell. 
In  this  manual,  the  aspect  of  the  linker  controlled  by  LinkEd 
files  is  referred  to  as  the  advanced  linker. 

The  advanced  linker  is  provided  for  programmers  who  require 
maximum  Rexibility  from  the  system;  for  most  purposes,  the 
standard  linker  is  completely  adequate.  When  a  statement  in  this 
book  applies  equally  to  the  standard  and  advanced  aspects  of  the 
APW  Linker,  the  terms  APW  Linker  or  linker  ^le  used. 

Because  all  Apple  llGS  Programmer's  Workshop  assemblers  and 
compilers  create  object  code  that  conforms  to  the  same  format, 
the  APW  Linker  can  link  together  object  files  written  in  any 
combination  of  the  development-environment  languages. 

Utilify  programs 

The  Apple  IlGS  Programmer's  Workshop  includes  several 
programs,  called  APW  Utilities,  that  perform  functions  not  built 
into  llie  shell.  Utilities  include  the  following. 

■  Compact,  which  makes  load  files  more  compact  so  they  load 
faster  and  take  up  less  space  on  disk. 

■  Crunch,  which  combines  multiple  object  files  created  by  partial 
assemblies  or  compiles  into  a  single  object  file, 

■  DumpOBj,  which  lists  an  object-module -format  file  to  standard 
output  C^jsually  the  saeen). 
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ewcutable  stqndt]rci'-Af>pi!a 
t^rograms, 


I  which  m:aiy^r^.s  [wD  fifes  or  dircaorie.  for  equaJiCy 

Iheir  coinenxs,  diies,  and  file  types,  ^■ 

■  Files,  which  lisls  Che  conlmts  of  a  dircaotv^  indudiil^ 
-^L^bdirectorie..  FiJes        also  .r.rch  for  .  file  whos^  nante 
contaio.s  a  scrmg  vou  specify, 

I  init,  which  JniEialii^es  aomvAis)  a  disk. 

'  MacGci,,  v^'h;c!l  geacrate^  a  cusconi  m^cro  n\v.  for  a  progrjra, 

MakeBIn  whkh  creates  .  ProDOS  e  binary  file  from  fro'  " 
Hj  Los  a  fjle. 

MakeUb,  wliich  creal.::,s  a  libriiy  nie  trom  object  files  or 
modifies  an  existing  library-  filii. 

which  searches  a  texl  or  sourc=e  iil^for  ^.Sitm^Mr 


Ihe  Apple  llsj  Doijuager  Is 
documentfld  In  \U^Applo  l/ss 
Dsbugger  f^efBfanca 


Apple  JIGS  Debugger 

Tc  ft  dllcace  the  debugging  of  prL>i,;ram3,  Apple  provides  a 

Tx^c  tSJ      Sir'  ^-^f^P--^     -h.Ch  t]r«  debugger  b,] 

^xecuuoi^  that  you  c^n  ir:.pecc  the  concenLi  of  the  regSers  ' 
memory,  direct  page,  and  stack,  ^^J^^^ers, 

sc^^n       udln^  a  d.sassenilily  of  the  code  being  ^aced  (he 

tTsnd  V  '^^^^'^^^  p'ogr...  being 

Apple  I  >  -  P-gr..'.  dire..  pa.e.  iht  co.Sllfof 

Apple  IlCi  register.,  and  the  <:onten.L,  of  che  prograrn's  st.ck. 

Because  the  de[-.,gger  c^.n  provide:  onJy  an  a.senibly-ianguase 
^Stn.g  0/  maci:ine  code,  it  Is  mo,.l  useful  for  <Ji^hasmTonm 
wr.ten  I.  ...embJ,  l.ngu.ge.  Ifoweve,  if  you  Sve  f go'?  '  * 
understanding  of  ho^v  your  hish-level-Jangrr.ge  pro^rlm  ^ 
co|np.led  ,nto  machine  code,  yr>u  car.  us.^  the  the  debiler  r. 
help  find  th:i  subrouline  conlsinin^  the  probJen:,  ^ 

^  A^OJtv  The  Apple  no?  Debugser  i,^  noi  pari  of  .y^W  It  is  a 
separate  pmduci,  av:ii!abie  t^:rough  ATDA,  See  Chapter  3. 
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See  Chapter  9  foi  more 
Wofmation  on  the  Appla 
ftograrnitier's  and  Developer's 
Aswclotlon  lAPDA), 


Language  considerations 

The  APW  package  includes  a  powerful  65816  assembler.  At  the 
time  of  this  prinEing,  the  other  languages  available  for  APW 
include  C  and  Pascal.  The  APW  environment  is  designed  lo 
support  any  number  of  programming  languages;  checii  with  your 
Apple  dealer  and  the  Apple  Programmer's  and  Developer's 
Association  to  find  out  what  other  languages  are  available.  Before 
you  purchase  any  language,  make  sure  that  it  creates  APW- 
compatible  files  and  provides  full  and  convenient  toolbox 
support. 

One  of  the  advantages  of  working  with  APW  is  that  the  object  files 
created  by  any  APW  assembler  or  compiler  are  compatible  with 
those  created  by  any  other  assembler  or  compiler,  'iliis  means 
that  you  can  link  together  routines  written  in  any  combination  of 
APW  languages  to  create  a  program. 

For  example,  you  can  write  an  application  in  a  high-level  language 
such  as  C  or  Pascal,  in  order  to  make  it  portable  to  other 
computers  and  to  speed  up  development  time.  Most 
programmers  find  it  faster  to  write  programs  in  high-level 
languages  than  in  assembly  language.  Once  the  program  is 
complete,  you  can  determine  which  routines  run  most  slowly  and 
then  write  assembly-language  versions  of  only  those  routines  to 
enhance  the  performance  of  the  prograriL 

❖  Parameter-passing:  The  exact  method  by  which  parameters  are 
passed  is  usually  of  no  concern  to  your  application  as  long  as 
you  work  in  a  single  language — your  language's  interface 
libraries  and  compiler  take  care  of  all  parameter  passing  to 
and  from  the  toolbox  and  among  routines.  However,  if  you  arc 
writing  a  segmented  program  where  parameters  are  passed 
between  routines  written  in  differsnt  languages,  you  need  to 
understand  the  parameter-passing  details  of  your  system.  See 
your  language  reference  for  futher  information. 
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Objeci  module  format  Is  defined 
n  fh©  Apple  ties  f^ogrammerS 
Workshop  Reference. 


Source  files,  object  files,  and  load  flies 

The  Appls  IIGS  uses  three  fundamental  types  of  program  f! 
source  files,  object  files,  and  load  files. 

■  code  and  data  a 
fellow  the  convenUon.  of  a  particular  programming  larlgi 

■  Object  flies  .re  binary  files  created  by  assemblers  arid  ^ 
dcX  intermediate  step  in  the  progZ 

H  f  Tru '  ^^'^^  ^^'^"^t  be  read  and  S 

^odified  like  source  files;  neither  can  Lhey  be  loaded  by  nB 

fiSTre  ::f;-  ^^"^  "^^'^  relatives  i;^^ 

mes;  are  used  only  as  input  to  tlic  linker. 

■  ll?^?K '^'""c  ^  ^'''^  "'^^'^"^      '^^  l^'^^^^-  I-o^d  flics  P 

to  the  Imker,  if  you  want  to  link  a  now  routine  to  a  proRramr 
must  go  back  to  the  object  files  to  do  so  ' 


input  I 


There  is  a  single  binary  file  format  used  by  APW  and  the  Ap 
COMF).  Although  OMF  defines  the  structure  and  record^L  of 

Seated  lo  ?rr'  -pressiX 
object  and  load  files  are  two  versions  of  the  same  thing  TTrey 

serve  different  purposes  and  are  read  by  different  programs. 


Symbolic  references  and  relocatable  code^ 

In  high-level  programmins  languages,  the  use  of  symbolic 
.=rere„„s  is  often  the  only  w»y  to  funtp  fto™  one  IS  k  ,  " 
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The  code  created  by  an  APW  compiler  normally  contains  no 
absolute  references,  and  so  need  not  be  loaded  into  a  specific 
location  in  memory.  It  is  referred  to  as  relocatable.  Note  that  this 
term  is  somewhat  misleading:  a  relocatable  program  can  be 
loaded  into  any  location  in  memory,  but  it  cannot  necessarily  be 
moved  once  it  has  been  loaded. 

The  term  relocation  in  this  context  means  the  process  of 
inserting  into  the  program  in  memory  Cor  patching)  the  actual 
memory  addresses  to  which  jumps  must  be  made.  Relocation  on 

Absolute  code,  febcotabia  the  Apple  IIGS  is  done  during  program  load  by  the  System 

code,  and  the  process  of  Loader 

(elocotion  by  the  System  Loader 

are  discussed  in  more  betali  In  When  source  code  is  assembled  or  compiledj  it  is  converted  into 

Chopter*.  object  code  containing  machine-language  instructions,  data,  and 

symbolic  references.  Before  the  program  is  actually  run,  the 
symbolic  references  must  be  resolved — they  must  be  replaced 
with  code  that  the  loader  can  use  to  patch  in  the  proper  addresses 
at  load  time.  The  program  that  resolves  the  symbolic  references  is 
the  APW  Linker,  (The  linker  gets  its  name  from  the  fact  that  it  can 
combine,  or  link  together,  several  object  files  to  create  a  single 
load  nieO 


Do  not  write  absolute  cod# 

The  advantages  of  using  relocatable  code  for  the  Apple  UGS  are 
considerable.  Relocatable  code  can  be  placed  in  memory  at 
whatever  location  the  Memory  Manager  chooses.  Because  desk 
accessories,  shell  programs,  RAM-based  tool  sets,  and  so  on  are 
placed  in  memory  by  the  System  Loader  and  Memory  Manager, 
absolute  code  is  likely  to  conflict  with  other  code  already  in 
memory.  It  is  very  unlikely  that  your  program  will  have  sole 
control  of  the  computer  when  it  executes. 

Object  module  format  exists  primarily  as  a  specification  for 
relocatable,  segmented  code,  The  Apple  liGS  System  Loader  and 
the  Memory  Manager  are  designed  to  support  relocatable  code. 
The  APW  Assembler  and  compilers  are  all  designed  to  generate 
relocatable  code.  It  is  easy  to  write  relocatable  code.  Da  not  write 
absolute  code. 


Source  files,  object  flies,  and  toad  flies 
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Four  steps  to  creating  a  program 

The  conversion  of  a  source  file  into  an  executable  program 
loaded  in  memory  is  done  in  four  main  steps,  as  follows  fand 
shown  in  Figure  7-2); 

1.  You  create  one  or  more  source  files  with  a  text  editor.  In  thi.;ikp 
you  design  the  prograiti,  create  its  data  structures,  and  write  HisJ> 
routines.  The  source  flleCs)  may  be  in  one  or  more  APW  hn^,,ip 

2  You  assemble  or  compile  each  source  file.  Depending  on  the 
programming  language  used  in  ihe  source  file,  the  APW 
Assembler,  C  Compiler,  or  some  other  assembler  or  compiler 
processes  the  source  file  to  create  one  or  more  object  files,  Tlie 
object  files  contain  65816  machine-language  instnioions,  data, 
and  symbolic  references  to  program  routines. 

Object  files,  then,  consist  of  machine-language  instructions  plji 
unresolved  symbolic  references. 

3.  You  link  the  object  files,  using  the  APW  linker.  The  linker  com- 
bines all  of  the  object  files  into  a  single  load  Hie  and  resolves 
symbolic  references.  The  linker  verifies  that  every  routine  refe;- 
enced  is  included  in  the  load  file;  if  there  are  any  routines  thjilfe 
linker  has  not  found  when  it  has  finished  processing  all  of  the 
object  files,  then  it  searches  through  any  available  library  files  for 
the  missing  routines.  The  linker  replaces  symbolic  references  with 
entries  m  special  tables  it  creates,  called  relocation  dictiooarles. 
The  load  file,  then,  consists  of  blocks  of  machine-language  coi 
that  can  be  loaded  directly  into  memory  (called  memory 
images),  plus  relocation  dictionaries  thai  contain  the 
information  necessary  to  patch  address  references  when  the 
program  is  loaded  into  memory. 

4  You  execute  the  load  file.  It  is  loaded  into  memory  by  the 
System  Loader.  The  loader  calls  the  Apple  lies  Memory 
Manager  to  request  blocks  of  memory  for  the  load  file  loads 
the  memory  images,  and  uses  the  relocation  dictionaries  to 
patch  the  actual  memory  addresses  into  the  machine-language 
code  in  memory, 

❖  Segments:  The  entire  load  file  is  not  necessarily  loaded  into 
memory  at  one  time;  all  OMF  files  are  divided  into  segments 
which  can  be  processed  independently.  OMF  file  segmentation i 
IS  a  fundamental  Apple  lies  concept— what  segments  are  is  " 
discussed  in  Chapters  1  and  6;  how  to  create  them  is 
considered  ncJtt. 
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FIgufe  7-2 

Creating  an  executable  Apple  Ifes  program 
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Segments 


When  you  write  a  program,  it  is  generally  considered  good 
programming  practice  lo  divide  ihe  source  code  up  into  smaller 
units  called  subroutines.  Subrouiines  make  ihe  program  easier  to 
write,  read,  and  modify, 

Similarly,  it  is  easier  to  link  a  program  if  the  object  files  are 
divided  up  into  smaller  units.  In  this  case,  we  call  the  units  abject 
segments. 

Load  files,  too,  can  be  easier  to  load  into  memory  if  divided  into 
smaller  units.  The  subuniLs  of  load  files  are  called  had  segi 


important    Although  1 1 1  s  sometimes  con ve  enf  to  use  the  sa  me  or  related 


diviaorns  for  subroutines,  object  segments,  and  load  segments.  It  is 
important  to  keep  in  mind  that  they  need  rrot  correspond,  An  otsjed 
segment  can  contain  one  to  many  subroutines,  and  a  Eoad 
segment  can  contain  on©  to  many  object  segments. 


The  proper  use  of  subroutines  (source-code  segments)  is  a  subject 
for  another  book.  How  to  create  object  segments  and  load 
segments  by  using  APW  is  discussed  in  the  following  sections. 


Defining  objecf  segments 

Each  APW  language  provides  some  means  for  specifying  in  youf 
source  file  the  subroutines  that  will  go  into  each  object  segment, 
and  the  name  of  the  object  segment.  In  some  languages,  such  as 
APW  Assembly  Language,  you  can  specify  the  start  and  end  for 
each  object  segment  and  can  include  any  number  of  subroutines 
within  the  segment.  In  some  languages,  such  as  APW  C.  each 
subroutine  becomes  an  object  segmerit  and  the  object  segment 
name  is  the  same  as  the  subroutine  name- 

Figure  7-3  illustrates  the  conversion  of  source-file  divisions  into 
object  segmenLs, 
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Figure  7-3 

Assigning  object  segments  In  your  source  code 


About  load  segments 

The  APW  Linker  creates  load  files  from  object  files  and  library 
files.  The  linlter  cannoi  extract  from  an  object  file  a  portion  of 
code  smaller  than  an  object  segment.  So,  to  the  linker,  the  object 
segment  is  the  fundamentai  unit  of  ar:  object  or  library  file.  The 
load  nte  consists  of  one  or  more  load  segments,  each  of  which  is 
loaded  into  memory  separately.  So,  to  the  System  Loader,  the 
load  segment  is  the  fundamental  unit  of  a,  load  file. 

Keep  in  mind  thai  object  segments  and  load  segments  are 
different  entities,  When  you  link  a  program,  you  tell  the  linker  into 
which  load  segment  you  want  each  object  segment  to  go.  You  can 
assign  any  number  of  object  segments  to  the  same  load  segment. 
You  can  assign  eacii  object  segment  to  its  own  load  segment, 
place  the  entire  program  into  a  single  load  segment,  or  anything 
in  between. 
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How  many  load  segments? 

It  is  not  gent5rally  necessary  or  desirable  to  divide  a  load  file  i 
into  too  many  pieces,  as  the  loader  must  handle  each  load 
segment  independently.  For  small  programs,  in  fact,  you  mayi 
to  have  a  single  load  segment. 

On  the  other  hand,  it  is  often  desirable  to  have  more  than  oil 
load  segment,  Because  two  consecutive  load  segments  do  aotl 
have  to  be  loaded  into  contiguous  memory  locations,  a 
segmented  program  may  load  into  memory  when  a 
nonsegmented  program  won't  lit.  In  fact,  it  is  necessary  to 
segment  some  programs,  because  the  65816  processor  does  .„ 
allow  single  blocks  of  program  code  larger  than  64K  to  be  load 
(there  is  no  such  restriction  on  blocks  of  data).  Programs  thai 
consist  of  segmented  load  files  can  often  be  started  up  more  1 
quickly  than  unsegmentcd  programs  because  not  all  the  load  j 
segments  have  to  be  processed  during  the  initial  load.  Some 
segments  can  be  left  on  disk  until  they  are  needed  (if  ever). 

What  is  the  optimum  number  of  load  segments  for  a  progrm'l 
Only  you  can  answer  this  question  for  your  own  program.  If  itisj 
small  program,  all  of  which  must  be  in  memory  for  the  prograi 
to  run,  a  single  load  segment  might  be  fine.  If  the  program  is  \t 
enough  that  machines  with  smaller  amounts  of  memory  might 
have  trouble  loading  it,  several  smaller  segments  might  be  betK 
Fortunately,  you  can  segment  your  load  file  during  the  link  staj 
of  program  development;  if  you  are  not  sure  how  many  load 
segments  will  be  best,  you  do  not  have  to  make  the  decision 
you  are  writing  the  source  code. 

Which  segments  should  be  dynamic? 

When  you  specify  load  segments,  you  can  designate  some  as 
dynamic.  A  dynamic  segment  is  loaded  automatically  by  the 
loader  and  Memory  Manager  when  it  is  needed  during  prq 
execution,  A  segment  that  is  not  dynamic  is  referred  to  as  st 
static  segment  is  loaded  at  program  boot  time  and  is  never 
unloaded  or  moved  during  execution. 
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Ovortays  are  program  segment? 
ttwtars  dterncrtely  loaded  at 
ftWcfly  1fie  some  memorv 
odciress,  No  two  overlay 
jeomenfs  cori  b©  In  memory  of 
thB  samettme,  and  no  other 
piogram  con  use  thiot  memorv 
rangg, 


When  the  System  Loader  first  loads  a  program,  it  loads  all  the 
program's  static  segments  and  then  passes  coniro]  to  the 
program.  When  any  pan  of  the  program  references  a  routine  in  a 
dynamic  segments,  the  loader  finds  the  dynamic  segment  on  disk 
and  loads  it.  The  dynamic  segment  then  remains  in  memory  for 
as  long  as  the  program  is  running,  unless  the  program  unloads  the 
segment  with  a  System  Loader  call.  Unloading  a  segment  makes  its 
memory  block  purgeable,  so  the  Memory  Manager  can  remove 
the  segment  from  memory  if  it  needs  space  to  load  some  other 
segment. 

One  segment  of  every  program — the  program's  main 
routine — must  be  static.  Any  other  segments  may  also  be  static, 
but  (especially  for  large  programs)  the  system  will  run  more 
efficiently  if  infrequently  used  segments  are  dynamic.  There  are 
several  advantages  to  designating  a  segment  as  dynamic.  Because 
dynamic  segments  are  not  loaded  until  they  are  needed,  for 
example,  the  initial  load  of  a  program  is  faster  if  some  of  the 
segments  are  dynamic,  Also,  if  there  is  a  possibility  that  the 
computer  will  mn  out  of  memory  while  your  program  is  mnning, 
you  can  use  dynamic  segments  to  allow  several  parts  of  the 
program  to  share  the  same  portion  of  memory. 

When  dynamic  segments  share  the  same  general  area  of  memory, 
they  are  similar  to  overlays.  However,  dynamic  segments  are 
much  more  versatile  than  overlays,  because  dynamic  segments 
(assuming  they  are  also  relocatable)  can  be  loaded  at  any 
location  in  memory  when  needed.  Furthermore,  one  segment 
need  not  be  removed  from  memory  to  load  the  next.  A  dynamic 
segment  that  is  not  being  used  is  removed  (purged  by  the 
Memory  Manager)  only  if  the  application  permits  it  (with  an 
unload  call),  and  only  if  the  memory  is  needed  for  something 
else.  Otherwise,  the  segment  remains  in  memory  and  need  not  be 
reloaded  the  next  time  it  is  called. 

For  large  programs,  you  will  probably  want  to  see  what  difference 
it  makes  to  designate  a  particular  segment  as  dynamic.  Sometimes, 
for  example,  it  may  be  more  desirable  to  accept  a  delay  in  the 
initial  load  of  a  program  than  to  have  the  program  pause  while  it 
loads  a  dynamic  segment  during  execution. 
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To  iry  out  a  segment  as  both  static  and  dynamic  you  can  eifl 

advanced  linker  when  you  link  the  file.  Most  APW  Janguam  la 
you  .peafy  .n  the  source  file  that  a  particular  load  ogZt  fe  fl 

rsin^i.C,  l'!\'^'^'^P''^^  ihe  program  to  change  the  type 
a  smgic  segment.  Either  way,  you  do  this  when  you  specify  loS 
segments,  as  described  next.  speaty  loaa  ] 


Unk£d.  the  stondord  tinker,  ond 
the  aavonced  linker  ore 
dfscussed  unds;  'Apple  I/gs 
Pmgrannmer's  Workshop,'  sarliei 
In  this  choptar. 


Assigning  load  segments  in  your  sourc^cod© 

You  oin  assign  object  segments  to  load  segments  with  sour«. 

.^otce  roSj  command^^Even  -Wou  iXk 

load-segment  assignments,  you  can  always  overriJ 

^sissTnt:' ^™ ^  ™  ~ 

In  APW  Assembly  Language,  for  example,  the  beginning  of  eachi 

can       these  d.rcctives  to  specify  the  name  of  the  load  st^m 
o  which  ead,  object  segment  should  be  assigned  by  n.  2.^ 
load  segment  name  in  the  operand  field  of  tSe  Live  ' 

and^I7  ?'  °"  ^^"""^^  is  an  object  sefim 

and  the  funcuon  name  is  u^e-A     ru^   u-  segm 

case  vou  u.^.  rhl  =  "''^^^^  segment  name.  Iq 

r       ^^^ment  directive  to  indicate  the  start  of  a  I. 

next  seg.,ant  directive  arc  assigned  f  the  same  load  segment. 
Figure  7-4  illustrates  the  assembly-language  method  u.J«.,h. 
-me  Object  nie  as  that  in  F.g..e  7-3.  Note  aho  tm  bZ^, 

ot^ject  segment-all  object  segments  without  load-sestment  m 
^re  put  mto  a  single  unnamed  load  segment. 
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Load  file 


MRIM     START  SETUP 


END 
START 

END 
START 

SETUP 

END 
DATA 
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END 
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Object  segment  w.:m 
Load  segment  nome:  setu? 


Obj&cl  segment  dave 
Load  segment  name: 


Object  segment  DHL 
Load  segment  name;  ssTUr 


Object  segment  paul 
Load  segment  name:  second 


Object  segment  end 
Load  segment  nome: 


Standard 
linker 


Segment  setup 


Segment 


Figure  7-4 

Assigning  ioad  Eegments  in  your  source  code 

If  you  use  ihe  standard  linker  (that  is,  if  you  do  not  use  a  LinkEd 
file),  ihe  source-code  load-segment  assignments  are  used  when 
you  link  [he  file.  Object  segments  assigned  to  the  same  load 
segment  need  not  be  contiguous  in  the  source  file;  in  fact,  they  do 
not  even  have  to  be  in  the  same  source  file.  The  linker  places  all 
of  the  object  segments  that  have  the  same  load  segment  name 
into  the  same  load  segment. 

❖  Order  of  segments:  The  order  in  which  the  linker  finds  the  load 
segment  names  in  the  source  file  is  the  order  in  which  it  places 
the  load  segments  in  the  load  file.  If  the  order  of  the  load 
segments  in  your  load  file  is  important,  then  you  must  either 
order  your  source  code  accordingly,  or  use  a  LinkEd  file  lo  link 
the  program. 

The  advantage  of  the  standard  linker  over  the  advanced  linker  is 
that  the  standard  linker  is  quite  automatic,  You  do  not  have  to  list 
cither  the  object  segments  or  the  load  segments  in  the  link 
command.  Library  files  in  the  APW  library  prefix  are  searched 
automatically,  and  you  can  specify  any  other  library  files  you  wish. 
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Inltlalteafion  segments  and  direct- 
pagg  stack  segments  ore 
discussed  In  Chapter  6. 


But  there  are  some  disadvantages  to  the  standard  linker: 

□  Ydu  must  aticr  the  iource  code  to  alter  load-segment 
assignments. 

□  Some  APW  languages  may  not  allow  you  to  assign  special  load] 
segment  types  (such  as  initialization  segments  or  direct- 
j>age/sta.ck  .segmenis)  in  the  source  code. 

□  All  of  the  object  segments  in  ihe  source  code  are  linked, 
whether  you  want  to  include  Ihem  in  the  load  file  or  not. 

If  any  of  these  restrictions  cause  a  problem  for  you,  you  can  j 
the  advanced  linker  to  link  the  file,  as  described  next. 


Assigning  load  segments  with  a  LinkEd  file 

The  APW  Linker  can  recognize  both  the  names  of  the  object! 
segmenis  in  an  object  file  and  the  names  of  the  load  segments^ 
any)  to  which  ihoso  object  segments  are  assigned.  You  can  i 
UnkEd  file  to  take  advantage  of  this  fact. 

For  example,  suppose  you  have  written,  compiled,  and  linkedj 
program  (using  the  standard  linker),  and  you  find  that  onelq  . 
segment  is  larger  than  64K.  Because  no  single  block  of  code  ll 
than  64 K  can  be  loaded  into  memory,  you  must  break  this  lo 
segment  into  smaller  pieces.  Rather  than  changing  the  load 
.segment  assignments  in  the  source  code  and  recompiling  the" 
program  J  you  can  link  the  program  with  the  advanced  linker,  usiflgi 
LinkEd  commands  to  specify  the  names  of  load  segments  and  the] 
object  segments  that  go  into  each  load  segment. 

Figure  7-5  illustrates  this  process.  Note  that  the  object  file  is 
identical  to  the  object  file  in  Figures  7-3  and  7-4.  Let's  assume  thai 
the  unnamed  load  segment  is  too  large.  By  using  a  DnkEd  file,!®] 
place  object  segments  dave  and  END  into  separate  load  segmenfevl 
named  NANClf  and  LAST,  respectively.  The  code  in  object 
segment  EtJD  has  been  put  at  the  end  of  the  program,  Theref(L 
we  have  accomplished  two  things  by  using  the  advanced  linkefrl 
have  split  one  large  load  segment  into  two  smaller  load  segn 
and  we  have  changed  the  order  in  which  the  code  appears  in  I 
load  file. 
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Assigning  load  segments  with  the  odvonced  linker 

The  advanced  linker  gives  you  the  freedom  to  ignore  source-file 
load-segment  assignments  and  lo  specify  it%to  which  load  segment 
eacli  object  segment  should  go,  U  also  lets  yau  specify  special 
segment  types  for  load  scgmcnis.  and  the  filename  and  file  type 
of  the  output  file.  On  the  other  hand,  you  must  specify  each  object 
file  to  be  included  and  each  object  segment  to  go  into  each  load 
segment. 

For  small  programs  with  only  a  few  object  segmer^ts  or  for  larger 
programs  with  a  simple  load-file  structure,  the  standard  linker  is 
easier  to  use.  If  you  are  developing  a  large  program  witli  many 
dynamic  segments  or  with  special  segments  .such  as  a  direct- 
page/stack  segment  or  initializaUon  segments,  the  advanced  linker 
gives  you  much  more  nexibilily.  By  changing  the  LinkEd  Hie,  you 
can  change  the  number  and  sequence  of  load  segments,  the 
object  nies  and  object  segments  linked,  and  the  segment  types  of 
load  segments,  I'or  such  a  program,  it  is  well  worth  the  Ume  and 
effort  to  learn  how  to  use  the  LinkEd  commands  and  to  write  a 
LinkEd  file. 
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^  IVote:  In  using  dynamic  segments,  it  is  iniportani  that  the 
volumes  conLaining  all  needed  segments  and  libraries  be  on 
line  at  nin  lime.  If  the  System  Loader  cannot  find  a  dynamic! 
segment  it  needs  to  load,  execution  halts  and  the  user  is 
requested  to  mount  the  proper  volume. 


A  global  symbol  Is  a  label  In  one 
iegmeni  that  con  be  rsferanced 
In  onothef  jsgment,  os  opposed 
to  □  focal  symbol^  which  can  be 
used  only  within  the  segment  In 
which  It  is  defined. 


Library  files 

Library  files  are  object  files  whose  segments  contain  routines 
useful  to  many  different  programs.  In  APW,  all  library  files  arei 
object  module  format,  regardless  of  the  language  of  the  source 
file.  An  Apple  IIGS  library  file  (ProDOS  filetype  SB2)  can 
therefore  be  used  by  a  program  written  in  any  source  language. 
Some  languages,  such  as  APW  C,  come  with  a  set  of  library  files 
used  by  that  language. 

A  library  Ole  includes  a  special  segment  at  the  beginning  of  the 
file,  called  the  library  dictionary  segment  The  library 
dictionary  segment  is  die  first  segment  of  a  library  file;  it  corns 
the  names  and  locations  of  all  the  global  symbols  in  the  file. 
The  linker  uses  the  library  dictionary  segment  to  find  the 
segments  it  needs. 

When  the  linker  processes  one  or  more  object  files  and  cannot 
resolve  a  symbolic  reference,  it  assumes  that  it  is  a  reference  to  i 
segment  in  a  library  file.  If  you  use  the  standard  linker,  it 
automatically  searches  all  of  the  files  in  the  APW  library  prefix 
(prefix  number  /2— usually  voiume/ APW /-LIBRARIES / ,  where 
volume  is  the  volume  name  of  your  boot  disk)  as  well  as  any 
library  files  you  specify  on  the  command  line.  If  you  use  the 
advanced  linker  (that  is,  if  you  use  a  LinkEd  command  file),  the  , 
linker  searches  only  the  library  files  that  you  specify.  Unless  you  I 
are  using  the  advanced  linker,  you  do  not  even  need  to  know  the  j 
names  of  the  library  files  in  order  to  use  them;  the  standard  lini 
automatically  finds  the  files  and  extracts  the  segments  i:  needi 


Creating  library  files 

You  can  create  your  own  library  files  from  one  or  more  object 
files  by  using  the  APW  utility  program  MakeLib.  Figure  7^5 
illustrates  the  library-file  creation  process.  You  specify  one  or 
more  object  files  to  be  included  in  the  library  file,  MakeLib 
concatenates  Lhe  files  and  creates  the  library  dictionary  segmenLj 
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The  library  dictionary  segment  makes  it  possible  for  the  linker  to 
search  a  library  file  for  global  symbols  (the  names  of  the 
subroutines  it  contains)  much  mone  rapidly  than  it  can  search  an 
object  file.  Consequemly,  the  linker  will  search  a  library 
dictionary  segment  several  times  if  necessary  to  find  segments 
referenced  by  other  segments  in  the  library  file,  and  ihe 
sequential  order  of  the  segments  in  a  library  file  is  not  important. 
But  if  you  use  several  library  files,  the  order  in  which  the  files 
occur  is  important  because  each  is  processed  only  once.  U  is  for 
that  reason  that  MakcLib  allows  you  to  include  several  object  files 
in  a  single  library  file. 


seal 


Eegn 


OblectFile  2 


segl 


I  ssgTT 


ObjectFlle  3 


segl 


segn 


MakeLib 


Figure  7-6 

Creoting  □  library  file 


LibraryFile 


Library 
Dictionary 
Segment 


segl 


segn 


segl 


segn 


segn 


MakeLIb  is  described  In  detaiE  In 
tfie  Apple  '/©s  Programmer's 
Workshop  RefBtencB. 


In  addition  to  creating  library  files,  the  MakeLib  utility  allows  you 
to  modify  existing  library  files,  and  even  to  recreate  an  object  file 
that  was  a  component  of  a  library  file. 


Creating  segmented  code:  three 
examples 

This  section  presents  examples  of  segmented  programs.  Three 
small  program  examples  are  provided;  a  program  consisting  of  a 
single,  static  load  segment;  a  program  containing  several  static 
load  segments;  and  a  program  using  dynamic  segments. 


Creating  segm&nted  code;  ttiree  examples 
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MAIN 


KEEP 

MCOPY 

START 

PHK 

PLB 

WRITELN 
LOh 
RTL 
END 


1 


❖  Note:  These  examples  are  simple,  text-based  sample  programi 
meant  only  to  illustrate  segmentation  concepts.  Your  prograiHi 
whether  segmented  or  not,  should  be  event  driven,  desku 
style  appiications. 


A  single,  sfatic  load  segment 

The  following  is  a  typical  sequence  for  writing,  compiling,  . 
linking  a  simple  one-segment  program.  It  has  only  one  SUA 
directive,  so  only  one  segment  is  created.  The  segment  is  n 
explicitly  made  dynamic,  so  it  is  static. 

1.  Boot  APW  and  set  the  system  language  to  the  language  tyjK 
the  source  code  you  intend  to  write.  We  are  going  to  write 
simple  assembly-language  file  for  this  example,  so  enter 
following  command: 

ASMS5S16 

Z  Set  the  default  prefix  to  the  subdirectory  you  want  to  use  _ 
your  files.  If  your  work  disk  is  called  /MYPROGS,  for  examp^ 
enter  the  following  command: 

PREFIX  /KYPKOqg 

3.  Open  a  file  for  editing.  We  will  call  our  source  file  HW.  EnterftT 
following  command; 

4  Write  the  source  code  for  your  program.  For  our  example,  i 
in  Ihe  following  program:  \ 


EDIT  m 


HELLO 

2/AINCLUDE/M16..UT1L 


# ' Hello  world ! ' 
*0 


Output  filename 
Macro  file 

Beginning  of  segment 
Set  data  bank  equal 

to  cade  bank 
Macro  that  writes  istrinq 
Set  error  code  to  0 
JiHturn  to  shell 
End  of  segment 
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5.  Press  Apple-Q  to  quit  Ihe  Editor,  When  the  Quit  menu  appears, 
press  S  to  save  the  file  to  disk,  then  E  to  return  to  the  APW 
Shell  command  line. 

6.  To  assemble,  link,  and  execute  the  file  HW,  enter  the  following 
command: 

RUN  HW 

The  words  Hello  world!  should  appear  on  the  screen, 
following  the  diagnostic  output  of  ihe  assembler  and  linker.  If 
they  do  not,  check  your  source  file  for  errors  and  try  again. 

7.  You  now  have  a  file  on  your  work  disk  called  HELLO.  To 
execute  this  program,  enter  HTiLLO  from  the  APW  Shell 
command  line. 

❖  Note:  This  program  cannot  be  executed  from  a  finder  or 
program  launcher.  It  must  run  under  APW. 


Several  static  load  segments 

It  is  often  desirable  to  write  a  program  that  consists  of  more  than 
one  load  segment.  For  example,  when  there  is  no  single 
contiguous  block  of  memory  large  enough  to  load  an  entire 
program,  the  program  may  still  be  loadable  if  it  is  divided  into 
several  load  segments.  The  program  that  follows  is  divided  into 
three  object  segments,  and  each  object  segment  is  assigned  to  a 
different  load  segment. 

This  program  also  illustrates  a  few  of  the  basic  functions  that 
See Chopter  8 for fgqulioments  tor       should  be  performed  by  any  shell  application  before  it  begins  to 
oppllcottons,  pjjj^.  reading  the  User  ID  assigned  to  the  program,  reading  the  ID 

of  the  shell  program  that  launched  it,  and  checking  the  command 
line  for  parameters.  This  sample  program  merely  prints  this 
information  to  the  screen;  an  actual  application  could  do  much 
more: 

□  It  could  use  the  User  ID  in  calls  to  the  Memory  Manager  and 
System  Loader. 

□  It  could  use  the  Shell  ID  to  determine  whether  it  was  launched 
by  the  shell  program  under  which  it  was  designed  to  run.  For 
example,  a  compiler  designed  to  run  under  APW  might  not  be 
able  to  run  under  ProDOS  or  urider  another  shell. 

□  It  could  use  the  parameters  on  the  command  line  for  whatever 
purpose  the  shell  application  was  created  to  fulfill. 
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The  program  listed  below  has  three  segments;  two  that  begin  i 
a  START  directive,  and  one  tliat  begins  with  a  DATA  directive,' 
program  assembles  into  the  object  segments  MAIN,  WRITE,  aK|J 
MSG,  which  arc  linked  into  the  load  segments  MAIN,  OUTPUT,  j 
LABELS,  respcciivel/.  To  create  the  program,  first  use  the 
following  commands  to  set  tJie  current  language  to  65816 
assembly  language  and  to  enter  the  editor: 


ASM65B16 

EDIT  SAMPLE. SRC 


Then  type  in  the  following  program: 


KEEP 

SAMPLE 

MCOPY 

SAMPLt.MACSOS 

MAIN 

START 

MAIN 

Start  segnwnt 

■it 

SET  UP  ENVIRONMENT 

CLIKE 

GEQU 

0 

Define  CLINE  as  direct  page 

Set  datd  bank  register  equal  to 

PLB 

program  bank  register 

STA 

[JSER,_ID 

Accumulator  fiolds  User  ID 

STTf 

CLINE 

X  and  Y  registers  contain 

STX 

CLIHE+-2 

pointers  t.o  commartcJ  line 

PUSHWORD 

asm  ID 

Convert  User  ID  to 

POSHLONG 

#tISEBID+l 

hex  number 

PtJSHWORD 

#4 

ASCII 

_INT2HEX 

string 

J5L 

WRITE 

Jump  to  next  segment 

RTL 

USER_ID 

ENTRY 

DS 

2 

Reserve  space  far  User  ID 

USERIO 

ENTRY 

STR 

1  ■ 

Reserve  space  for  User  ID  ASCII 

END 

WRITE  START  OUTPUT 

*  WRITE  USER  ID  TO  SCREEN 

USING  MSG 

PUSH1.0NG  #U3RMSG 

_WRITECSTRIKG 

PUSH LONG  tUSERlD 

_WRITEL1KE 

LDA  CLINE 

0"^  CLINE+2 


Start  second  segment 

Use  data  in  data  segment 
Pointer  to  output  string 
Writes  'User  ID  =  ■ 
Pointer  to  User  ID  ASCII  string 
Writes  User  ID,   Carriage  Ret 
If  pointer  to 

coinmarid  line  -  0, 
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#0 
#8 


[CLINE] , Y 


BUE  LBl 

PUSHLONG  tSOLMSG 
_WRITECSTRING 

JSR  LBS 
white  shell  id  to  screen 

pushlong  #idmsg 
_writecstring 

LDY 
UJX 
PHX 
PHY 

PDSHWOBD 
_MRITECHAR 
PLY 
FLX 
INY 
DEX 

pax 

PLX 

PUSHWORD 
_WRITECHAR 
WHITE  COMMAND  TO  SCREEN 

PUSHLONG  *COMMSG 
__WRlTECSrRItIG 
LDY 
PHY 
LDA 
AND 
CMP 
BEQ 
PHA 

_WRirECHM 
PLY 
IBY 

PHY 

IRA 

PUSHWDRD 
_WRITECHAR 
WRITE  PAEU\METERS  TO  SCREEN 

PtISHLOHG  #PARMSG 
HRITECSTRING 


LB2 


#8 

[CLINE] 
#$007r 

V  • 

La4 


LB3 


no  command  line 
Pointer  to  output  string 
Writes  'No  command  line' 
If  no  command  line,   go  to  end 

Pointer  to  cjutput  string 

Writes    'Shell  ID  =  ' 

Use  "i  for  cjffaet  into  shell  ID 

Shell  ID  ia  8  eharSj  ose  X  for  counter 

Save  X  on  stack 

Save  y  on  9taclc 

Push  nejtt  letter  of  shell  ID  on  stack 

Wcite  one  char  oC  shell  ID 

Pull  Y  from  stack 

Pull  X  from  stack 

Increment  Y 

Decrement  X 

Save  X  on  stack 

SavB  Y  on  stack 

compare  X  to  0 

Return  to  LB5  if  X  not  0 

Pull  Y  from  stack 

Pull  X  from  stack 

Write 

Carriage  Return 

Pointer  to  output  string 

Writes   'Corainand  is  ' 

Use  Y  for  offset  into  command  line 

Save  ¥  on  stack 

Load  next  character  into  accumulator 

Just  look  a  t  low  7  bits 

Test  for  space  character 

Stop  after  first  space 

Push  next  letter  of  command  on  stack 

Write  one  char  of  command  string 

Pull  Y  from  stack 

Increment  Y 

Save  Y  on  stack 

Return  to  LB3 

Carriage  Return 


Pointer  to  output  string 
Writes  'Parameters  are' 
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LB  6 


LB7 
LBS 


PLY 
INY 
LDA 
AND 
BEQ 
PH¥ 
PBA 

_WR1TECHAR 

PLY 

INY 

BRA 

PUSHWORD 

_WHITECHAR 

LDA 

RTL 

END 


[CLINE3 , t 
#?OOFF 


fSOD 

to 


Pull  ¥  from  stack 
Increment  ¥ 

Load  next  character  into  accumulatot 
Test  for  Null 
Stop  aftec  Suli 
Save  ¥  on  stack 

Push  next  letter  of  parameters  on  stao 
Write  one  char  of  parameters 
Pull  ¥  from  stack 
Increment  Y 
Return  to  LBS 
Carriage  Return 

Set  return  code  to  0 
Saturn  to  segment  Haiii  to  end  rQutine 
EntJ  of  segment 


MSG 

IDKSG 

U3RMSG 

COMMSG 

PARt'^SG 

NOLMSG 


DATA 

DC 

DC 

DC 

DC 

DC 

END 


^S^^^S  Begin  data  segment 

C Shell  ID  is:  ',H'00' 

C'Dser  ID  is;  ',K'0{)' 

H' OA' jC'Coinmand  Is:  ',^'00' 

H ' OA ', C ' Parameters  are;  ',H'OCJ' 

C'No  Command  Line. ",H' 00' 

End  data  segment 


Press  Apple-Q  to  quit  the  Editor.  When  the  Quit  menu  appeais, 
press  S  to  save  the  Die  to  disk,  ihcn  E  to  return  to  the  APW  ShdS 
command  line. 

The  program  uses  macros  in  several  places,  including  macros  fot 
calls  [o  the  Integer  Math  Tool  Set  and  the  Text  Tool  Set.  Execute ' 
the  following  command  to  create  a  macro  file  for  the  program 

MACG£N  SAMPLE. SRC  SAMPLE. MACROS  5 /AINCLUDE/M16 .TEXTTOOL  2 /flINCLUDE/Ml 6  DTIL 
S/AINCLUDE/Mie . INTMATH 

To  assemble  and  link  the  program,  use  this  command: 

ASML  SAMPLE 

To  run  the  program,  enter  this  command; 

SAMPLE  ONE  TWO  BUCKLE  MY  SHOE 
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The  output  should  look  Like  this  fthe  actual  User  ID  will  var>',  as  a 
new  one  is  assigned  each  lime  the  program  is  run): 

User   ID  is:  1129 
Shell  ID  is:  BYTEWBKS 
Coiw.and  is:  SAMPLE 

Paraimeters  are:     ONE  TWO  BUCKLE  MY  SHOE 


Dynamic  segments 

As  an  eitample  of  a  program  with  dynamic  segments,  we  can  take 
the  same  niultiscgmem  example  we  jusi  created  and  make  one 
segment  dynamic.  What's  more,  we  won't  have  to  rewrite  a  single 
line  of  the  program's  code  or  re-assemble  it  to  do  so. 

To  make  the  second  segment  of  the  program  dynamic,  you  can 
link  the  program  with  a  LinkEd  file.  First,  if  you  have  not  done  so 
already,  assemble  the  program  {without  linking  it)  with  the 
following  command: 

ASSEMBLE  SAMPLE 

Use  the  following  commands  to  set  the  current  language  to  the 
LinkEd  language  and  to  enter  the  editor: 

LINKED 

EDIT  SftMPLE.LlHK 

Type  in  the  following  LinkEd  program: 

KEEP  SAMPLE 
SEGKENT  MAIN 

SELECT/SCAN  SAMPLE. STD  (HAIN) 
SEGMENT/DYUflMIC  OUTPUT 
SELECT/SCAN  SAMPLE. STD  (WRITE) 
SEGMENT  LABELS 
SELECT/SCAN  SAMPLE. STD  (MSG) 

Press  Apple-Q  to  quit  the  Editor.  When  the  Quit  menu  appears, 
press  S  to  save  the  file  to  disk,  then  E  to  return  to  the  APW  Shell 
command  line. 

lixecuEe  the  following  command  to  link  the  program: 

ALIRK  SAMPLE. LINK 
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The  APW  Linker  execuies  this  LinkEd  file.  Each  SEGMENT 

command  starts  a  new  load  segment:.  Each  SELECT/SCAN 
command  scans  through  the  files  with  ihe  root  filename 
SAMPLE  .  STD  for  the  object  segment  named  in  parentheses.  Tte 
load  segment  OUTPUT  is  dynamic.  The  load  file,  sample, 
contains  four  segments;  the  fourth  load  segment  is  the  Segment 
Jump  Table,  created  by  the  linker. 

When  you  launch  this  version  of  SAMPLE,  the  first  and  third 
segments  are  loaded  immediately,  but  the  second  segment  is  noE 
loaded  as  part  of  the  initial  load.  When  the  JSL  to  WRITE  is 
executed,  the  loader  loads  the  second  segment. 

*  Unloading:  Note  that,  once  loaded,  the  dynamic  segment  H 
remains  in  memory  throughout  execution  of  the  program.  Ti 
make  this  segment  available  for  automatic  unloading  by  the 
Memory  J^anager,  you  must  include  an  Unload  Segment  callU 
the  end  of  the  segment. 


Debugging 

A  variety  of  software  insmjments  exist  to  help  you  locate  and 
correct  errors  in  your  Apple  IIGS  programs.  Some  are 
sophisticated  and  some  are  simple.  Although  nothing  can  make 
debugging  easy,  the  more  experience  you  gain  with  these  aids,  [he 
more  erfidently  you  can  fmd  and  solve  problems. 


Classic  desk  accessories  are 
descflbed  undof  "Supporting 
Other  Desktop  Features'  In 
Chapter  5. 


Debugging  with  desk  accessories 

The  fact  that  Apple  IlGS  code  is  rypkaliy  relocatable  can  be  i 
problem  during  debugging.  You  can't  control  where  the  loader 
puts  your  program,  and  once  it  is  in  memory,  you  have  no 
obvious  way  to  locate  it.  How  can  you  debug  something  you  cairt 
even  find? 

Loader  Dumper  and  Memory  Mangier  are  two  classic  desk 
accessories  (CDA's)  provided  with  the  Apple  IIGS  Debugger 
Cde.scribed  later  in  this  section).  They  can  give  you  very  basic, 
and  Uius  very  important,  information  on  exactly  where  in 
memory  all  the  parts  of  your  program  are.  Furthermore,  because 
they  are  desk  accessories,  they  are  instantly  available  from  within 
your  program  or  debugger. 
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Loader  Dumper 

Loader  Dumper  is  a  classic  desk  accessory  that  permits  you  to 
dump  (print  out)  the  System  Loader's  data  structures:  the  Memory 
Segmeni  Table,  Paihname  Tabic,  Jump  Table,  Loader  global 
variables,  load-segment  information,  and  other  information  used 
by  the  System  Loader. 

A  principal  use  of  Uie  Loader  Dumper  is  to  get  your  program's 
User  ID  from  the  Pathname  Table.  Then,  using  Memory  Mangier 
(described  next),  you  can  find  out  where  in  memory  all  your 
program's  segments  are. 

Memory  Mangier 

Memory  Mangier  is  a  classic  desk  accessory  that  can  give  you  a 
listing  of  all  allocated  memory  blocks  with  their  associated  User 
ID  s,  sizes,  addresses,  attributes,  and  other  information. 

Most  commonly,  you  would  use  Memory  Mangier  to  inspect  all 
your  programs'  segments  and  buffers  in  memory.  They  arc 
identified  by  User  ID,  which  you  might  have  obtained  from 
running  Loader  Dumper.  Once  you  have  found  a  segment  you 
want  to  look  at  more  closely,  you  can  go  directly  from  Memory 
Mangier  into  the  Apple  IlGS  Debugger  or  into  the  Monitor 
program  (described  next),  to  do  detailed  inspection  and 
debugging. 

*  Note:  Memory  Mangier  also  allows  you  to  execute  Memory 
Manager  calls,  so  you  can  use  it  as  an  exerciser  program,  lo 
practice  calls  before  writing  them  into  your  code.  Even  though 
this  is  not  a  direct  debugging  function,  it  is  very  useful  because 
you  need  to  understand  the  Memory  Manager  well.  Memory- 
management  errors  are  among  the  most  common  and  most 
elusive  bugs  on  the  Apple  IIGS. 


Debugging  with  the  Monitor  program 

The  Apple  lIGS  Monitor  program  is  a  set  of  ROM-based  routines 
that  give  the  user  direct  access  to  program  code  in  memory. 
Using  the  Monitor,  you  can  perform  these  tasks; 
□  Inspea  and  modify  the  contents  of  any  location  in  memory,  in 
either  hexadecimal  or  ASCII  format. 

O  Move,  compare,  or  fill  ranges  of  memory. 


Debugging  247 


The  Monstor  progfam  ond  how  to 
can  If  are  dsicribed  In  t[^&  Apple 
ties  Firmware  Reference. 


The  debugger  Is  described  in 


□  Search  for  specified  patterns  in  memory. 

o  View  and  change  the  contents  of  various  microprocessor  an 
software  registers  and  flags.  croprocessor  an 

□  Execute  programs  from  within  the  Monitor. 
Q  Disassemble  code  in  memory. 
O  Use  the  mini-assembler  to  assemble  small  programs, 
A  special  convenience  of  the  Monitor  is  that  you  can  call  i,  fr 
wahm  the  program  you  ar.  debugging.  To  do      howeve  ™  ^ 
muM  make  the  call  fr.m  bank  SOO,  and  the  mac^ne  mus  te™ 

set  to  zero  and  w.th  tlic  direct  page  equal  to  the  zero  nase  InoT 
words,  the  mad.ne  must  look  exactly  like  a  standard  fjpt  f 
A  second  method  is  to  make  a  Miscellaneous  Tool  Set  caU  to 
mvoke  the  Monitor.  In  thi.  case,  the  machine  mus  b  inti 
nauve  mode  and  .he  Memory  Manager  must  have  I^en  s^J 
up.  -me  call  can  be  made  from  anywhere  in  memo^ 

Debugging^lfhThTAp^e^^ 

m.l?^'^  'i'''  ""'^"^^^  your  program  . 

memory  ar.d  lo  run  through  it  under  the  debuggers  coZ 
f^ogram  executes,  you  can  examine  the  come^rof^ 
65816  s  reg,.tcr.,  of  your  program's  direa  page  and  stack 

imeract  wnh  the  program  as  required,  returning  to  the  debu= 
display  at  breakpoints  that  you  set,  or  when  thl^^gar^^aJ 

SastembI  ^'^P'^^  ^  assembly-language  1 

HZ  '™'^^,™^<^^c.r  recreate  your  source  code  from  machine 
code.  Therefore,  the  debugger  is  easiest  to  use  with  assTmblv 

a  neip  get  you  started  debugging  your  program. 
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Debugging  segmented  programs 

In  order  to  use  the  Apple  IIGS  Debugger  to  debug  a  segmented 
program,  you  must  know  where  in  memory  each  segment  has 
iieen  loaded.  Tn  the  case  of  a  dynamic  segment,  you  must  know 
whether  it  has  been  loaded  and,  if  so,  where.  This  information  is 
available  through  the  Loader  Dumper  desk  accessory,  described 
earlier  in  this  section. 

To  load  your  program  by  using  the  debugger  and  to  determine 
where  in  memory  each  segment  is  loaded,  use  the  following 
procedure: 

1.  Start  up  the  debugger. 

2.  Use  it  to  load  your  program  into  memory, 

3.  Call  the  Loader  Dumper  from  the  desk  accessories  menu. 

4.  Use  ihe  Loader  Dumper  to  get  the  User  ID  of  your  program. 

5.  With  that  User  ID,  use  the  Loader  Dumper  to  get  a  listing  of  all 
your  program's  load  segments  and  their  memory  addresses. 

You  now  have  several  possible  courses  of  action  open  to  you.  If 
you  do  not  have  any  idea  in  which  load  segment  your  program  is 
crashing,  you  can  start  by  running  the  program  until  it  crashes 
and  then  examining  the  debugger  display  to  determine  the 
location  of  the  problem  insiuiciion.  If  you  know  in  which  segment 
the  problem  lies,  you  can  go  immediately  to  that  segment,  or  you 
can  set  a  breakpoint  at  the  beginning  of  that  segment  and  run  the 
program  until  it  stops  automatically  at  tliat  breakpoint. 

Wotching  o  running  disassembly 

If  your  program  does  not  require  any  input  from  the  keyboard, 
you  can  watch  a  disassembly  on  the  debugger  screen  as  the 
program  executes  to  find  the  exact  location  at  which  it  goes 
astray.  This  technique  will  probably  be  useful  only  for  short 
programs  or  programs  that  crash  almost  immediately  upon 
execution,  because  the  program  will  execute  very  slowly  while  the 
debugger  display  is  on  the  screen. 

To  run  your  program  under  control  of  the  Apple  IICS  Debugger, 
with  a  running  disassembly  appearing  on  the  screen,  use  the 
following  procedure: 

1.  Load  your  program  with  the  debugger. 
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Z  Put  the  debugger  in  single-step  mode,  starUng  at  the  first 
Instruclion  of  your  program.  Watch  the  contents  of  the  reg 
and  the  stack  (and  any  specific  memory  locations  you  have 
specified)  as  you  execute  individual  commands. 

3-  You  can  leave  single-step  mode  and  execute  commands 
automaLically  in  quick  succession  by  entering  trace  mode.  Yo 
program  will  begin  executing  under  debugger  control,  one 
instruclion  at  a  time  in  rapid  succession.  Once  in  trace  mode,- 
you  can  stop  execution  ai  any  time  and  then  return  to  single- 
step  mode 

In  trace  mode,  when  your  program  executes  a  BRK  instruction 
execution  stops.  The  last  instruction  executed  (the  BRK 
instruction)  is  displayed  on  the  screen,  along  with  the  previous 
several  instructions  executed,  A  BRK  instruction  is  actually  a  null| 
(a  zero  byte);  because  such  an  instruction  is  not  a  normal  part  i 
a  program,  the  fact  that  your  program  executed  one  probably 
means  that  some  previous  instruction  sent  the  program  of f  to  L_ 
wrong  place  in  memory,  With  luck,  the  instaiction  that  sent  yourl 
program  off  into  Xever  Never  land  will  still  be  on  the  screen. 

Using  breakpoints 

If  you  have  to  interact  with  your  program  in  order  for  it  to  njn,  ifl 
you  have  some  idea  of  which  segment  contains  the  bug,  or  if  yoal 
just  want  to  execute  the  program  more  quickly,  you  can  set  one  ol 
more  breakpoints  before  running  the  program.  A  breakpoint  is  il 
location  at  which  ttte  debugger  suspends  execution  of  the 
program,  giving  you  the  opportunity  to  examine  the  disassembly? 
and  the  state  of  the  machine  at  that  location. 

To  set  breakpoints  and  run  the  program  under  debugger  control  j 
try  the  following  procedure: 

1.  Load  your  program  with  the  debugger. 

2.  As  described  above,  use  the  Loader  Dumper  routine  to 
determine  the  starting  locations  of  the  load  segments  of  your 
program. 

3.  Back  in  the  debugger,  set  breakpoints  at  the  beginning  of  eadij 
load  segment  (if  you  do  not  know  in  which  segment  the  bug 
lies)  or  at  the  beginning  of  any  segment  that  you  want  to 
examine  more  closely, 
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4,  Run  your  program  under  debugger  conirol,  with  the  debugger 
display  turned  off.  When  the  debugger  comes  to  a  breakpoint, 
the  program  halts  and  the  debugger's  display  appears  on  the 
screen,  showing  the  location  of  the  instruction  at  which  the 
program  stopped  and  other  pertinent  information.  You  can 
also  view  a  disassembly  of  the  program,  starting  at  the 
breakpoint  location. 

5.  While  at  a  breakpoint  you  can  switch  to  single  step  mode.  Step 
through  the  segment  one  instruction  at  a  time  while  watching 
the  cements  of  the  stack,  the  machine's  registers,  and  up  to  19 
mennory  locations  you  specify.  From  single-step  mode,  you  can 
return  to  executing  the  program  auton^atically. 

If  at  any  time  during  execution  of  the  program  a  dynamic  segment 
is  loaded,  you  can  pause  execution  of  your  program  and  go  back  to 
Loader  Dumper  to  find  out  where  in  memory  it  has  been  placed. 

Breakpoints  can  be  used  for  purposes  other  than  And  in  g  a 
particular  segment,  Suppose,  for  example,  that  your  program 
seems  to  run  all  right  for  awhile,  then  crashes  after  having  lulled 
you  into  a  false  expectation  of  success.  In  this  case,  it  is  possible 
that  some  routine  is  failing,  not  the  first  time  it  Ls  run,  but  only 
after  going  through  several  iterations.  To  handle  such  a  situation 
without  stopping  the  program  every  time  the  routine  is  executed, 
you  can  include  a  trigger  value  for  a  breakpoint.  The  debugger 
counts  the  number  of  times  it  encounters  the  breakpoint,  and 
suspends  execution  only  when  the  trigger  value  is  reached. 

If  you  must  execute  a  routine  at  full  speed  in  order  for  it  to  work 
correctly,  you  can  insert  rsal  breakpoints  into  the  code.  When  you 
do  so,  Ihe  debugger  actually  inserts  BRK  instructions  into  memory 
at  the  breakpoint  locations.  Trigger  values  work  for  real 
breakpoints  that  you  have  set;  the  debugger  will  still  suspend 
execution  any  time  it  encounters  a  BRK  instruction  that  you  did 
not  set  as  a  breakpoint, 
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Using  memoiy  protection  ranges 

It  may  be  thai  certam  poriions  of  your  code  must  be  executed  at] 
ifie  full  speed  of  the  65816  microprocessor.  To  cause  this  to 
happen  automatically  every  time  you  trace  through  the  program,! 
you  can  set  any  areas  of  memory  you  choose  a,-}  code  trace 
ranges.  When  the  program  executes  a  jump  to  a  location  within  i 
code  trace  range,  the  debugger  relinquishes  control  to  your 
program  and  the  code  is  executed  at  fuU  speed.  'Ilie  poriioa  of 
memory  used  to  run  tool  calls  is  automatically  set  as  a  code  tno 
range  when  you  load  the  debugger. 

You  can  also  set  one  or  more  portions  of  memory  (the  limits  <rf 
your  code  as  revealed  by  loader  Dumper,  perhaps)  as  code- 
window  ranges.  If  the  program  attempts  to  execute  code  outside 
the  code-window  ranges  you  have  set,  execuUon  stops.  You  might] 
want  to  set  a  code-window  range,  for  example,  if  your  program  bj 
executing  a  jump  to  some  incorrect  memory  location  and 
trashing  memory  before  it  stops,  forcing  you  to  reboot  the 
machine  every  time  you  try  to  run  the  program  with  the  debu( 

If  your  program  loads  a  dynamic  segment  during  execution  and 
you  want  to  pause  as  soon  as  control  is  transferred  to  the  dy 
segment,  you  can  set  code  window  ranges  to  include  all  the  static] 
segments  at  the  start  of  the  program.  Then  when  [he  dynamic 
segment  is  loaded  and  control  is  transferred  to  it,  the  program 
will  be  outside  any  code  window  range  and  execution  will  stop. 


Important 


Once  you  hovs  set  any  code-window  range,  no  code  wlil  be 
executed  that  is  not  In  a  code-window  range.  Ttierefore,  if  yousetc 
cod©-window  range  equal  to  the  memory  locotlon  of  one  of  you  , 
program  segments,  you  must  set  code-window  ranges  for  all  other 
segments  ttx3t  It  calls. 


Debugging  multiple-language  programs 

One  of  the  advantages  of  using  the  APW  development 
environment  is  that  it  allows  you  to  link  together  rouiijies  wrilisn 
in  different  programming  languages.  Ttiis  facility  can  lead  to 
unique  problems,  however,  especially  when  information  is  passed 
between  routines  written  in  different  languages. 
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The  PtoDOS  16  Exerciser  Is  on  the 
dlslt  that  accompanies  the  Apple 
SGS  ProDOS  16  neferenca 


Parameter  passing  may  fail  in  your  program  for  any  of  several 
reasons:  you  mighi  have  used  a  wrong  variable  lype,  for  example, 
or  a  called  rouUrie  might  expect  to  receive  parameters  in  a 
differenl  order  from  the  way  ihey  were  passed  by  a  calling  routine. 

To  use  Uie  Apple  IIGS  Debugger  to  debug  parameter-passing 
problems,  use  the  following  procedure: 

L  Set  breakpoims  at  the  beginning  of  the  calling  segment  and  at 
the  beginning  of  the  called  segment. 

Z  Run  the  program  in  trace  or  real-time  mode  until  the  first 
breakpoint  is  reached.  Search  this  segment  to  find  the  JSL  that 
calls  the  other  segment. 

3.  Set  a  breakpoint  just  before  the  JSL  that  calls  the  second  segment. 
You  can  remove  the  other  two  breakpoints  now  if  you  wish, 

•4.  Run  the  program  until  the  JSL  breakpoint  is  reached. 

Parameters  are  normally  passed  either  on  the  stack  or  in  the  A, 
X,  and  Y  registers.  The  actual  information  passed  may  be  a 
pointer  to  the  data  rather  than  the  data  itself.  By  examining  the 
contents  of  the  registers,  the  stack,  and  memory,  determine  the 
location  of  the  parameter  being  passed,  and  see  if  it  has  the 
value  you  expect, 

5,  Execute  the  JSL.  The  return  address  should  have  been  added  to 
the  stack. 

6,  Step  through  the  segment  in  single-step  mode.  Is  the  called 
routine  reading  the  parameters  passed  to  it,  in  the  proper  form 
and  order?  By  a  careful  study  of  the  action  of  the  called 
routine,  you  should  be  able  to  determine  the  source  of  the 
problem. 

7,  If  all  parameters  are  being  passed  correct] y,  perhaps  the 
problem  occurs  when  tlie  results  are  passed  back  to  the  calling 
routine.  Find  the  RTL,  and  study  the  stack  and  registers  as 
before  to  determine  whether  the  results  are  being  passed 
correctly  back  to  the  calling  routine. 


The  ProDOS  16  Exerciser 

The  ProDOS  16  Exerciser  is  a  program  that  allows  you  to  practice 
making  operating  system  calls  in  a  controlled  environment, 
before  coding  them  into  your  applications. 
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The  ProDOS  l6  Exerciser  is  not  really  a  debugging  tool,  but  you 
can  use  it  in  several  ways  during  the  debugging  process.  For 
example; 

□  By  pracUcing  the  ProDOS  16  calls  you  intend  to  use  in  your 
program,  you  can  "debug"  them  in  the  sense  that  you  can  see 
exacUy  how  ihcy  function,  before  writing  them  into  your  code, 

□  Because  the  Exerciser  gives  you  direct  access  to  file  attributes, 
you  can  use  it,  for  example,  to  change  file  types  (such  as  from 
$B5  to  SB3)  without  having  to  enter  APW. 

□  The  Exerciser  allows  you  to  inspect  and  modify  the  contents  of 
any  portion  of  memory,  and  any  block,  on  a  disk— but  see  \hi 
warning  below. 

□  The  Exerciser  allows  you  to  enter  the  Monitor  program 
directly.  Once  in  the  Monitor,  you  can  use  its  debugging 
facilities,  as  described  earlier. 


Warning     The  ProDOS  16  Exerciser  allows  you  unconstrained  use  of  all  ProOOS 
16  colls.  Including  those  that  modify  disk  directories  and  blocks,  It 
also  permits  you  to  modify  any  porHon  of  tnemory,  Includirg  that 
occupied  by  system  software  or  by  the  Exerciser  Itself.  You  can 
easily  destroy  the  contents  of  a  disJ<  or  cause  a  system  crash,  Be 
car^lul  what  you  modUyl  lu  j 
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Chapter  8 


What  Type  of  Program 
to  Write? 
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A  list  ofall  defined  file  types  Is 
given  under  "The  ProDOS  RIe 
Svsfem'rn  Chaptef6 


Under  ProDOS  16  on  the  AonJf  ™ 
classified  by  file  tyoe  Sort  ?f    ?  ^o^puter,  programs 

this  chap;;;;  ^""^"^  f''-  'yp^«.  given 

a  general  appIicaUons  CfiJe  type  $B3J 

□  «ng  program,  such  as  shells,  switchers,  and  oper 

°  I'n  uSr  ^'^^  ^^^^  ''''^  ^-."C. 

°  'les'^  accessories  (file  types  SBS  and  iB9) 

□  initialization  files  (file  types  $B6  and  $B7) 

□  mternjpt  handJers 

D  user  tool  sets  (fife  type  $BA) 

wnung  some  of  the  other,  more  soedal  nuZ  "^"^ 
^nrorm.ion  in  this  chapter  c..Z^7^;Z7:nT'^^^^ 


General  applicahons 


needs.  Por  .  woX'^^^^^^^^^^^^  '1^' 

and  language  interore  rr,  L       y      '  'P^'^^^^i'^et  programs, 

code  nils,  as  ^<:^T:s^:^i;s:::::  ^^'^  t 

^^ces.ori.s,  and  utilities  ^hat  m.'s  /e^^omtr"' 

are  not  applications.  proerams; 


Chopter  6:  What  Type  of  Progrom  to  WrJfe? 


To  be  a  Cstantl-alonf;)  application,,  an  Apple  IIG^  pny^rAm  nvx-xis 
to  meel  ceriain  requife.frient.s.  \i.  rmifil 

□  ijOLisist  of  execuia  bio  ni  a  cb  i      s  n  gii  ngu  code 
r  Ix:  ill  Apple  KG S  objecl  module  i'onmi 

n  hnvi;  a  file  type  of  Jli:^ 

n  u-s;:  V'lciDOS  1 6  as  its  o pirating  system 

J  obscrvt!  lIjl:  ProDOS  l6  QUIT  convenuon.s 

□  gel  lill  Tu:t;dcd  mernoiy  from  ihe  Memory'  Mmiagci- 

AH  other  aspects  of  ihe  proyrsKd  aic  up  to  yOU-  But  of  comm-. 
wircciyly  iccDmn?ei"Ld  lhal  you  design  y<.)ur  progacns  to  use  the 
Apple  desk i op  iciT.csfaoe  and  follow  the  Apple  I  findLiis  Interface 
Guideiiries. 

*  l-'roDC.iS  Sr  The  above  I  [St  referi;  specifically     Ajiple  IlCS 
applications  thai  n.in  ucides-  ProDOS  l6,  Requiremeni.s  for 
prog  I  amis  thai  run  under  f^roOOS  R  :-irc:  quite  ditferens;  see  Ihe 
Pnynos  ^?  Tiichnical  Re/'c fence  Manual 


Utikm  it  self-booling? 

There  are  iwo  ways  lo  nnaki;  your  type  SB 3  appliCiition  seif- 
hooiing,  so  that  li  15  auiomaticaily  loaik^d  and  launched  ai  systetti 
sLanup: 

n  Give  it  the  lilenan^e  extension  .  SVTjifi.  By  using  this  me;hod, 
h'mlXJS  e  syalerri  piogfcm?  afo  your  pro^jrani  Ixl«uik;.s  a  ProDOS  36  equivalent  to  a  PrnDO>  8 

dfiscrlbed  In  iTie  PfgDOSB  sy^iem  program  on  si  sliicidarii  Apple  TI  computer. 

Yc-chnlcc!  Rcfsrencf^  Monuoi 

□  Giv<3  ir  the  filenanie  START  and  place  it  in  the  SYSTEM/ 
subdirectory.  By  using  this  method^  your  prr>g[am  substitutes 
for  iht;  RmliT  or  program  launcher  that  normally  rxoiiuLo-s  ficiU 
on  the  Apple  iirra 

In  c.Lilf]{':T  case,  your  proRam  must  be  the  first  (or  only)  [n'ogram 
with  the  proper  fiicnarui:  or  filename  extension  that  the  boot 
loatier  program  encoL;nters  on  yht.-.  boot  disk.  Figure  S-1  diagrams 

for  a  more  detailed  dcsclotlon  of       the  progi  acn  selecLioo  sequence  at  system  siaririj:. 

sy^leni  slurlup,  aee?  the  App!s  lies 
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(Boot  sequence: 
the  file  ncjmed 
PRO  DOS  Is  executing!) 


Is  there  q  file  named 
/V /SYSTEM/START? 


yes  no 


Is  there  a  .SYSTEM 
or  .SVS16t(te'? 

yes 


Which  found  fli^t? 
.SYSltflle  found  first 


no 


Fotal  errsf 


.SYSTEM  file  found  first 


Execute  a 
ProDOS  16 
QUIT  call, 
using  the 
filename 
of  the 
SYS16 
program 


(.SVSI6  program  executes) 


Execuls  an 
enhanced 
ProDOS  3 
QUIT  call, 
using  the 
filename 
of  the 
.SYSTEM 
prt>gram 


(.SYSTEM  program  eKscutes) 


load  and 
execute 


/V/SYSfEM/STABT 


START  Is  fypicaily 

O  pr09rcm 
selector/finder 


Figure  6-1 

Startup  program  selection 


I 


❖  Noie:  Apple  recommends  Ihat  you  do  not  name  your 

application  start— leave  Jiat  name  for  a  program  launcher 
or  finder.  If  you  give  your  program  a  clearly  identifiable  name, 
the  user  can  more  easily  launch  it  from  any  boot  disk. 
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Chopter  6:  What  Type  of  Program  to  WtJte? 


IfjB  concepts  of  dofmanf  ond 
fflsfartabl©  pfograms  are 
SscLJSsed  under  'Loading 
Rrograms  and  Segments"  In 


R>(  more  InlofrmaHon  on  the  APW 
C  language,  see     Apple  tiGS 
Ptogiammef's  Wcfkshop  C 
ffe/er&nca 


Make  it  restartable? 

If  you  want  your  program  to  be  able  to  be  quickly  relaunched 
from  2  dormant  state  in  memory,  it  needs  to  be  restartabie.  A 
resiartable  program  reinitializes  all  its  variables  each  time  it  gains 
control,  withouL  having  to  read  in  files  or  segments  from  disk.  It 
also  makes  no  assumptions  about  the  state  of  the  computer,  such 
as  register  contents  or  Hag  settings,  when  it  gains  control.  !f  all 
initializaUon  information  is  in  code  statements  in  your  program's 
initialization  segments  and  static  code  segmentCs),  the  program 
should  be  restartabie. 

It  is  difficult  for  programs  in  some  languages  to  be  restartabie.  In 
C,  for  example,  all  global  variables  are  in  segments  named 
-GLOBALS  and  ~ARRAys,  which  must  be  initialized  each  time  the 
program  starts  up.  To  get  around  this  difficulty,  the  System  Loader 
supports  the  concept  of  RELOAD  segments.  A  RELOAD  segment  is 
a  static  data  segment  that  is  loaded  from  disk  whenever  an 
(otherwise)  restartabie  program  is  launched  from  a  dormant  state 
It  contains  whatever  initialized  data  is  needed  by  the  program,  the 
rest  of  the  program's  static  segments  (other  than  initialisation 
segments)  are  not  loaded  at  that  time. 

When  your  application  quits,  it  passes  a  parameter  to  ProDOS  16 
{and  thence  to  the  System  Loader)  stating  whether  the  application 
is  restartabie  or  not.  You  must  determine  when  you  write  the 
program  what  type  it  really  iS;  neither  ProDOS  l6  nor  the  System 
Loader  will  check. 


Controlling  programs 

A  controlling  program  is  a  program  thai  loads  and  executes  other 
programs  while  itself  remaining  active  in  memory.  An  application 
needs  to  be  a  controlling  program  only  if  it  must  remain  in 
memory  after  it  calls  another  program.  The  APW  Shell  is  a 
controlling  program;  ProDOS  l6  is  a  controlling  program. 

Writing  a  controlling  program  is  far  more  involved  than  writing 
an  application,  This  book  does  not  show  you  how  to  write  a 
conu-olling  program;  bui  if  you  do  write  one,  please  follow  ilie 
guidelines  below.  They  specify  how  your  controlling  program 
Ptogroms  thQT  run  under  shells  or©       communicates  with  shell  applications.  Sec  also  the  next  section, 
caJledihell  opplicationsand  ore         "Shell  Applications,"  for  more  information  on  how  controlling 

Ills  tVDO  r  r  *  ^ 

^  programs  and  their  subprograms  interact. 
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ProDOS  la  register  ond  cElfBct- 
pogeystock  conventions  ate 
discussed  under  'Setting  Up 
Direct- Page/Stock  Space"  In 
Chapter  6,  and  futiy  described  In 
til©  Apph  IIGS  ProDOS  16 
Iteferanca 


See  "QuEtttng  and  Launching 
Under  PtoDOS  16*  In  Chapter  6. 


□  Your  controlling  program  should  use  the  System  Loader's 
Iniltal  Load  funaion  to  load  Lhe  subprogram.  Initial  Load 
returns  the  subprogram's  starting  address  and  User  ID  to  yo 
controlling  program.  When  your  controlling  program  passe 
execution  to  the  subprogram,  it  should  pass  the  subprograii 
User  ID  in  the  accumulator. 

□  Your  controlling  program  may  also  pass  parameters  and  d 
identifier  string  to  the  subprogram,  as  described  under  "Stiel 
Applications." 

□  Your  conirolling  program  is  responsible  for  establishing  thd 
appropriate  input  and  output  vectors  for  its  subprograms.  Fd 
example,  when  ProDOS  l6  launches  a  program,  it  initializes] 
Text  Tool  Set  to  use  the  Pascal  I/O  drivers  for  the  keyboard  j 
and  80-column  screen. 

□  Unless  all  its  subprograms  include  direct-page/stack  segmen| 
your  controlling  program  must  provide  a  default  direct- 
page/stack  space  for  any  subprogram  that  it  launches.  The 
controlling  program  should  observe  the  ProDOS  16 
conventions  for  register  initialization  and  direct-page/stadc 
allocation. 

□  Shell  applications  can  terminate  with  either  an  RTL  instnictJ 
or  a  ProDOS  16  QL'IT  call,  If  any  of  its  subprograms  might  q 
QUIT,  your  controlling  program  must  intercept  all  ProDOS 
calls  so  that  when  the  subprogram  quits,  the  controUing 
program,  rather  than  ProDOS  l6,  regains  control. 

□  Your  controlling  program  is  totally  responsible  for  disposiiij 
of  the  subprogram.  When  the  subprogram  is  finished,  the 
controlling  program  must  remove  it  from  memory  and  releJ 
all  memory  resources  associated  with  it^  User  ID.  The  bestwi 
to  do  this  is  to  call  the  System  Loader's  User  Shutdown 
funcUon.  If  the  program  ends  in  a  QUIT  call,  your  controllil 
program  is  responsible  for  performing  any  other  system  tasl^ 
normally  done  by  ProDOS  16  in  response  to  a  QUIT. 
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Sbb  'Loading  Pfograms  and 
Ssomenti'  In  Chapter  6  for  a 
dicussion  of  controlling 
programs  ond  the  System 
loadffl's  Initial  Load  function. 


See  an  exampls  of  reading  an 
Identifier  string  In  the  second 
samplB  piogram  under  "Creating 
Segmented  Code:  Three 
Ejwmples'  In  Chapter  7. 


Shelt  applications 

Shell  applications  (ProDOS  l6  file  type  $B5)  are  executable  load 
files  ihat  are  run  under  a  controlling  program  such  as  the  APW 
Shell.  The  controlling  program  launches  Che  shell  application  by- 
calling  the  System  Loader's  Initial  Load  function,  and  transfers 
control  to  the  shell  application  by  means  of  a  JSL  instruction, 
rather  than  launching  the  program  through  the  ProUOS  l6  QUIT 
function.  Therefore  the  shell  does  not  shut  down,  and  the 
program  can  use  shell  facilities  during  execution. 

A  shell  application  typically  returns  control  lo  its  shell  with  an 
RTL  instruction.  With  a  shell  (such  as  the  APW  Shell)  that 
intercepts  ProDOS  l6  calls,  the  shell  application  can  end  with  a 
ProDOS  16  QUIT  call. 

Shell  applications  should  use  standard  Text  Tool  Set  calls  for  all 
nongraphics  I/O;  the  controlling  program  is  responsible  for 
initializing  the  Text  Tool  Set  routines. 

❖  Stand-alone:  A  shell  application  can  run  alone  under  ProDOS 
l6  if  it  requires  no  support  other  than  standard  input  from  the 
keyboard  and  output  to  the  screen,  ProIXJS  \6  initializes  the 
Text  Tool  Set  to  use  the  Pascal  I/O  drivers  (discussed  in  the 
Apple  UGS  Toolbox  Reference  for  the  keyboard  and  80- 
column  screen.  To  be  launched  this  way,  a  program  must  first 
be  changed  to  file  type  $B3,  and  it  must  end  with  a  ProDOS  l6 
QUIT  call, 

As  soon  as  a  shell  application  is  launched,  it  should  save  the  value 
of  its  User  ID,  passed  in  the  accumulator  from  the  controlling 
program.  It  should  also  check  the  X  and  Y  registers  for  a  pointer 
to  the  shell-idcntincr  string  and  input  line.  The  X  register  holds 
the  high-order  word  and  the  Y  register  holds  the  low  ordcr  word 
of  this  pointer.  The  controlling  program  is  responsible  for 
loading  this  pointer  into  the  Index  registers  and  for  placing  the 
fotlowing  information  in  ihe  area  pointed  to; 

o  An  3-byte  ASCII  string  containing  an  identifier  for  the  shell. 
The  identifier  for  the  APW  Shell,  for  example,  is  BYTEWRKS. 
The  shell  application  should  check  this  identifier  to  make  sure 
that  it  has  been  launched  by  the  correct  shell,  so  that  the 
environment  it  needs  is  in  place.  If  the  shell  identifier  Is  not 
correa,  the  shell  application  should  write  an  error  message  to 
standard  error  output  (normally  the  screen),  and  exit  wtih  a 
ProDOS  l6  QUIT  call  (if  the  controlling  program  supports  it) 
or  an  RTL. 


Shell  applications 
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For  more  Infofmatton  on  direct 
page  and  stack  oJlocaflon,  see 
'Setting  up  Dfrect- Page/Stock 
Space'  in  Ctiapter  6,  Sae  also  the 
Apple  liGS  ProDOS  16  Refsienca 


□  A  null-terminated  ASCII  siring  comaining  the  input  line  fori, 
shell  application.  The  shell  can  strip  zny  I/O  redirection  or 
pipeline  commands  from  the  input  line,  because  those  i 
commands  are  intended  for  the  shell  itself,  but  must  pass  cm 
mput  parameters  intended  for  the  shell  application. 

*  ProDOS  16:  ProDOS  l6  does  not  support  the  identifier  simi 
or  input  line  convention.  When  an  application  is  launched! 
ProDOS  16,  the  X  and  Y  registers  contain  zeros. 

If  the  shell  application  doe*  not  have  a  direct-page/stack  segn 
It  can  expect  tl:e  controlling  program  to  provide  a  1024-byte 
memory  block  in  bank  $00  for  the  shell  application  to  use  foria 
direct  page  and  Slack.  Whether  the  shell  application  spcdfiesaj 
tlircct-page/stack  segment  or  accepts  the  default,  the  address! 
the  Stan  of  the  dircct-page/siack  segment  should  be  in  the 
register  (D),  and  the  stack  pointer  (S  register)  should  point  tol 
last  ai.ghest-address)  byie  of  the  block  containing  the  direct- 
page/stack  segment. 

Some  shell  applications  may  launch  other  programs;  for  examp 
a  shell  nested  within  another  shell  would  be  a  controlling  i 
program  as  well  as  a  shell  application.  Such  an  application 
follow  the  conventions  for  both  types  of  programs. 

A  shell  applicaiion  should  use  the  following  procedure  to  quit 

1  If  the  shell  application  has  requested  any  memory  buffers  it 
must  release  (dispose  of)  them. 

2  The  shell  application  should  place  an  error  code  in  the 
accumulator.  If  no  error  occurred,  the  code  should  be  SOOOO. 
Ihe  code  SFFFP  can  be  used  as  a  general  (nonspecific)  error  i 
code.  Other  error  codes  are  up  to  the  controlling  program  to 
define  and  handle,  f  i'  b  «j 

3.  The  shell  application  should  execute  an  RTL  or  if  the  shell 
supports  it,  a  ProDOS  16  QUIT  call. 


Desk  accessories 

A  desk  accessory  is  a  small  program  that  a  user  can  mn  withouti 
closing  down  an  already-running  application.  The  Apple  IlGS  ^ 
supports  two  difTerent  kmds  of  desk  accessories: 
■  Classic  desk  accessories  (CDA'S)  are  designed  to  e:^ecute  in  x 

non-desktop  environment,  The  CDA  iniermpts  the  applicatic 

and  gets  full  control  of  ihe  computer. 
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For  Wl  details  on  the  Desk 
Manager  and  Its  desk  accessory 
juppport,  see  'Desk  Manager"  In 
fie  Apple  lIGS  Toolbox 
Safaienca 


m  New  desk  accessories  C]>fI>A'S),  on  the  other  hand,  are  designed 
to  execute  in  a  desktop  environment.  As  such,  Ihey  operate  in  a 
window  and  arc  subject  lo  the  same  rules  as  an  event-driven 
application.  They  are  not  stand-alone  applications,  however, 
because  they  rely  upon  another  application  to  start  up  the 
Apple  IIGS  tools. 

Neither  type  of  desk  accessory  has  a  lot  of  extra  programming 
overhead  apart  from  the  actual  task  the  accessory  performs.  Both 
types  depend  heavily  for  support  upon  the  Apple  IIGS  tool  set 
called  the  Desk  Manager. 


Writing  classic  desk  accessories 

A  classic  desk  accessory  must  start  with  a  header  consisting  of  a 
name  string,  a  pointer  to  the  start  of  the  code,  and  a  pointer  to 
the  shutdown  routine. 


StartofCDA 


str'Naine  of  DA' 

dc  14  '  StartOfDACode' 

dc  14 'ShUtDowfiSouCine' 


;  DA  name   (this  is  An  flPW  macro) 
;  Pointer  to  start  of  code 
;  Pointer  to  shutdown  routine 


When  a  CD  A  gets  control  from  the  Desk  Manager,  the  processor 
is  in  full  native  mode.  Because  the  Desk  Manager  has  already 
saved  the  necessary  parts  of  the  old  environment,  the  CDA  can 
concern  itself  solely  with  its  own  work. 

A  CDA  follows  this  basic  procedure: 

1.  It  initialises  for  the  machine  environment  it  needs.  The  Desk 
Manager  has  already  saved  the  old  state  when  the  CDA  gets 
control. 

Z  It  does  the  aaual  work  of  the  CDA.  Like  ail  Apple  DGS 

applications,  a  CDA  should  ask  the  Memory  Manager  for  any 
space  that  it  needs,  In  addition,  the  CDA  must  leave  the  stack  as 
it  was  when  the  CDA  got  control. 

3.  It  returns  to  the  Desk  Manager  with  an  RTL.  The  Desk  Manager 
then  automatically  restores  the  old  state  and  returns  to  the  desk 
accessory  menu. 

Every  CDA  must  have  a  shutdown  routine.  The  shutdown  routine 
is  called  every  time  the  Desk  Manager  shuts  down. 

Classic  desk  accessories  have  llie  ProDOS  file  type  $B9.  On  disk, 
they  must  be  in  the  DESK .  ACCS/  subdirectory  of  the  SYSTEM/ 
directory. 
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Writing  new  desit  accessories  ] 

AJl  new  desk  accessories  are  loaded  from  the  disk  at  boot  tia 
When  an  NDA  gets  control  from  the  Desk  Manager,  the  pre: 
is  in  full  native  mode.  By  convention,  the  NDA  can  assume 
the  tool  sets  shown  in  Table  8-1  have  already  been  loaded  aiid 
started  up.  If  the  NDA  needs  any  other  tool  sets,  it  must  load 
start  them  up  itself. 

Table  8-1 

Tool  sets  loaded  and  available  to  new  desk  accessories 
fool  set 


Tool  Locator 
Memory  Manager 
Miscellaneous  Tool  Set 
QuickDraw  H 
Event  Manager 
Window  Manager 
Control  Manager 
Menu  Manager 
LineEdit  Tool  Set 
Dialog  Manager 
Scrap  Manager 

Note;  The  NDA  may  also  assume  that  the  Print  Manager  is  available, 
although  not  necessarily  loaded  and  siancd  up 

A  new  desk  accessory  has  a  structure  fundamen tally  differem  fm 
that  of  a  desktop  application.  For  one  thing,  it  has  no  event 
loop— it  relies  on  the  application's  event  loop  and  the  Desk 
Manager  to  open  it,  prod  it  into  action,  and  dose  it.  For  another, 
it  has  only  four  nonprivate  routines:  init,  open,  acdon,  and  dost 
□  The  Desk  Manager  calls  the  init  routine  to  initialize  the  NDA 
when  the  Desk  Manager  starts  up,  and  again  when  it  shuts  dom. 
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□  The  Desk  Manager  calls  the  opsn  rouUne  when  the  NDA  is 
selected  by  Ihe  user  from  the  Apple  menu.  The  open  routine 
opens  the  desk  accessory  window  and  returns  a  pointer  to  it. 

□  The  Desk  Manager  calls  the  action  routme  in  response  to  an 
event  within  the  NDA  window,  or  when  a  specified  time  period 
has  passed,  or  if  a  selection  has  been  made  from  an  NDA 
menu  or  the  Edit  menu,  and  in  other  special  cases.  The  action 
routine  performs  whatever  tasks  the  ^^DA  was  designed  for.  An 
action  code  passed  in  the  accumulator  tells  the  N'DA  why  it  was 
called. 

□  11:6  Desk  Manager  calls  the  close  routine  to  close  the  desk 
accessory  window. 

The  processor  is  in  full  native  mode  on  entry  into  all  four 
routines.  All  four  routines  should  end  with  an  RTL  instruction. 

An  NDA  action  routine  follows  this  basic  procedure: 

1.  It  saves  important  global  values,  such  as  the  application's 
current  GrafPort. 

Z  Based  upon  the  action  code  received,  it  takes  appropriate 
action, 

3.  It  restores  the  global  values  and  returns  to  the  Desk  Manager 
with  an  RTL. 

You  must  start  the  NDA  with  an  identincation  section  that 
specifies  the  pointers  to  the  four  routines,  the  NDA's  period  Oiow 
often  it  runs),  its  event  mask  (what  events  it  wants),  and  iLs  menu 
tine  (text  defining  its  title  on  the  Apple  menu).  For  example,  the 
identincation  section  could  look  like  this: 


dc  14 'PtrToOpen' 
dc  14 ' PtrToClose ' 
dc  14 'PtrToflctlon ' 
dc  14 'PtrToInit' 
dc  12 'Period" 
dc  12 ' EvQntMask ' 
dc  c'   MenuLine\H"* ' 

dc  ll'O' 


Pointer  to  open  routine 
Pointer  Co  close  routine 
Pointer  to  action  routine 
Pointer  to  init  routine 
How  often  to  run 
what  events  to  retrieve 
Text  for  menu  item 
Terminator  for  the  menu  line 


New  desk  acces.sories  have  the  ProDOS  file  type  SB8.  On  disk,  they 
must  be  in  the  DESK .  ACCS  /  subdirectory  of  the  SYSTEM/ 
directory. 
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Initialization  files 


Initialization  files  are  files  of  types  $B6  and  SB7,  in  the 
SYSTEM. SETUP  Subdirectory.  They  are  special-purpose  progfimj 
that  perform  mi[ializaiion  at  system  suriup,  before  any 
applications  have  been  launched. 

There  are  two  types  of  initialiTiaiion  files — iemporary  and 
permaneni: 

■  Temporary  initialization  files  (type  SD7)  are  loaded  and 
executed  just  :ike  applications  (SB3),  except  that  they  must 
terminate  with  an  RTL  rather  than  a  QUIT.  'Oiey  are  removeii 
from  memory  when  finished. 

■  Permanent  Initialization  files  (type  SB6)  are  loaded  and 
executed  just  like  applications  C$B3>,  except  for  these 
conditions; 

□  They  must  not  be  in  special  memory. 

c  They  cannot  permanently  allocate  any  direct-page/siack 
space. 

□  They  must  terminate  with  an  RTL  rather  than  a  QUIT. 

Permanent  initialization  files  are  nol  removed  from  memorjr 
when  finished. 

With  initialization  files,  you  can  customize  the  operating 
environment  before  any  applications  are  loaded  The 
TOOL ,  SETUP  file  is  an  example  of  an  initialization  file;  it  loads 
RAM  patches  to  tool  sets.  TOOL.  SETUP  is  a  permanent 
initialisation  file  because  other  system  software  needs  it  during 
program  execution.  If  your  initialization  files  need  to  execute  omf 
once,  make  them  temporary. 

❖  jVofe.  Don't  confuse  these  initialization  files  (programs 
executed  at  system  startup)  with  initialization  %egmenls  (pieces 
of  an  application  executed  when  the  application  stans  up).  See 
"Loading  Programs  and  Segments"  in  Chapter  6. 
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Ion  ot  an  ongoing 
om  while  a  hlgher-prlorltv 
fam  Is  executed.  It  is  usuolly 
external.  hardwao-genGfated 
L  but  software  Interrupts  ore 


Intermptis  a  signal  to  o 
putar  that  stops  ttie 


When  the  Iniermpi  Request  GKQ)  line  on  the  Apple  IIGS 
microprocessor  is  activated,  or  when  a  software  interrupt  occurs, 
the  microprocessor  stops  execirling  the  current  application  and 
transfers  control  to  the  firmware  interrupt-processing  routines. 
The  built-in  inierrupt  handler  processes  the  interrupt  if  the 
application  has  not  provided  its  own  interrupt  handler, 


The  built-in  interrupt  handler 

The  Apple  IlCS  buik-in  interrupt  handler  is  a  firmware  program  that 
performs  a  sequence  of  steps  to  handle  system  interrupts.  When  a 
program  is  interrupted,  the  handler  saves  the  current  state  of  the 
system.  The  handler  then  processes  the  interrupt  itself  or  passes 
execution  to  another  handler,  either  internal  or  external,  On  com- 
pletion of  inierrupt  processing,  the  interrupted  program  regains 
control  and  can  continue  as  though  nothing  had  happened. 

Figure  8-2  and  the  following  explanation  give  a  simplified  picture 
of  the  steps  taken  by  the  built-in  interrupt  handler;  ihey  emphasize 
the  course  of  execution  when  the  interrupt  is  lo  be  serviced  by  a. 
user-ir^stalled  handler. 

1.  When  an  interrupt  signal  occurs,  execution  jumps  indirectly 
through  the  interrupt  vector  EIRQ  if  running  in  emulation 
mode  when  the  interrupt  occurred,  or  NIRQ  if  in  native  mode. 

Z  The  system  then  tesLs  to  see  whether  the  interrupt  was  the  result 
of  a  software  Break  instruction.  If  it  was,  the  system  vectors  to  a 
break  handler  through  a  break  handler  vector  in  bank  $E1.  If 
no  break  handler  is  installedn  execution  passes  through  the  user 
break  vector  at  $3F0  in  bank  zero,  which  normally  points  to  the 
Monitor  program. 
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3.  If  the  interrupL  source  was  not  a  Break  instmction,  the  inteS 
handler  saves  ihe  absolute  minimum  amount  of  information 
about  the  machine  state — -just  that  necessary  to  read  an 
incoming  serial  character— and  then  tests  for  AppleTalk  aud  , 
serial  port  intermpls.  This  hasty  action  is  necessary  so  that 
incoming  characters  in  high-speed  transmission  will  not  be 
lost.  If  the  interrupt  is  a  serial  interrupt,  the  firmware  executes  i 
}SL  instruciion  to  the  serial  port  handler. 

4  If  the  interrupt  is  not  a  serial  intermpt,  the  interrupt  handler 
saves  the  rest  of  the  machine  SEate  and  establishes  a  specific 
interrupt  memory  configuration,  as  described  next  under 
vironment  Handling  for  Interrupt  Processing,"  It  begins  a  [ 
loop,  testing  each  of  the  possible  interrupt  sources  in  turn,  j 

5.  If  no  internal  interrupt  handler  claims  the  interrupt,  then  (sjid] 
only  then)  the  firmware  jumps  through  the  user  interrupt 
vector,  to  a  user-installed  routine  that  handles  the  interrupt 
The  address  of  the  user  interrupt  routine  is  found  in  bank  $00, 
addresses  S3FE  Oow  byte)  and  S3FF  (high  byte). 


65C816 
interrupt 
vectors 
(Bark  SFF) 


EIRQ 
NIRQ 
etc. 


Sovesom* 

jtoto  inio 

^  Switch  to  high  speed 

yes 


Br&Ok  hondler 
(if  installed) 


JSL  AppleTc* 

JSL  Seridllrt 


(S3F0) 
Bank  SOO 


(Usually  Itie  monitor) 


no 

Save  more  stofe  tnfo, 
poll  oil  ottver  touTcm* 

 »-JSL 

 ^JSL 

 ^  JSL 

If  none  claims  it 

r 

User  Inlvnvpt  vector 
mPE)  In  Bank  $00 

Figure  8-2 

Built-in  interrupt  handler  (simplified) 
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Environment  handling  for  Interrupt  processing 

For  each  type  of  interrupt,  the  processor  can  be  in  either 
emulation  or  native  mode.  The  built-in  interrupt  handler  must 
save  the  current  environment  in  each  case,  set  the  interrupt 
environment,  process  the  interrupt  through  the  appropriate 
interrupt  handler,  and  then  restore  the  original  environment 
before  returning  control  to  the  intermpted  program. 

The  Interrupt  envlroiunem  is  the  machine  state  that  your  inter- 
rupt handler  finds  when  it  gains  control.  If  your  handler  is  called 
from  the  user  interrupt  vector,  the  environment  includes  these 
condiLions: 

□  emulation  mode 

□  slow  speed  (IMH^ 

□  text  page  1  switched  in  (main  screen  holes  available) 

□  main  memory  switched  in  (for  reading  and  writing) 

□  $DO0O-$FFFF  ROM  mapped  into  bank  $00 

□  main  stack  and  zero  page  switched  in 

□  main  stack  pointer  active  (auxiliary  stack  pointer  saved) 

If  your  handler  is  called  through  a  JSL  from  the  built-in  handler 
before  jumping  to  the  user  interrupt  vector,  the  same  state  applies 
except  that  the  machine  is  in  S-bit  native  mode  and  running  at 
fast  speed. 

*V  ProDOS  16:  If  your  interrupt  handler  is  installed  through 
PRoDOS  l6,  the  machine  slate  it  fmds  is  somewhat  different. 
See  "Interrupt  Handling  Under  ProDOS  16,"  later  in  this 
section, 

After  the  intermpt  has  been  processed,  the  system  interrupt 
handler  restores  the  environment  and  registers  to  their 
preinterrupt  state  and  executes  an  RTI  (return  from  interrupt), 
returning  to  the  executing  program. 
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Descfjptions  and  locofions  of  all 
inteffypt  vector  are  (Isted  )n 
Appendfx  D  of  Apple  Uqs 
RrmwQfB  Raferenc& 


Interrupt  soft  iwltches  are 
doGumsnted  uncfer  "Soff 
Switches'  In  th©>\pp/e 
Fifmwafe  Reference. 


Writing  and  installing  your  own  interrupt  hondler 

If  yu  write  yaur  own  interrupt  processing  routine  you  can  and 
u  to  the  system  by  mocl.fying  the  intem^pt  vector  loc.^ionr^ 
.  the  user  .mcrr.pt  vector  at  $00  03FE.  However  ™ 

[He  Appie  Has  Pirmware  Reference  regarding  interrupt  'i 
processing,  and  make  sure  to  restore  the  inimlt^nlirnnrnJ 

system  m  turn  to  restore  the  environmem  to  its  origin.]  state 
Ji  must  do  the  following  tasks. 

1-  Verify  that  the  interrupt  c.me  from  the  expected  source. 
2  Handle  the  interrupt  appropriately, 
3-  Clear  the  appropriate  interrupt  soft  switch. 
4.  Restore  evcryihirtg  to  the  state  it  was  in  when  the  intermpt 

:^:rte7?  theTa^hL^^^^  ^^'^  ^ 
'  S^c^ '^'^^-P'  --'i^K  an  m 

Here  are  .some  other  factors  to  remember  when  you  a,e  de 
wuh  programs  that  run  in  an  interrupt  environmen" 

°  S."se  t^e  Tr""''''  T ^"^'^^'^^  -«^ni, 

°  ISearna^e'  'T^"^''       ^"^^'^"^'^     ^^"^  ^»  only, 
mem"'  jtX^'  T^^^^      ^PP-'^^  everywhere'^ 

°  LTrd\S;h  an^o  i—pt  handier:.' 
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Interrupt  handling  under  ProDOS  16 

You  can  write  an  interrupt  handler  and  install  it  under  ProDOS 
16,  if  you  wish.  ProDOS  16  installs  its  own  vector  at  location  $00 
03FE  (page  3  in  bank  lero),  so  when  an  internjpt  occurs,  execution 
passes  through  that  location.  At  that  point  the  microprocessor  is 
running  in  emulation  mode,  using  the  standard  dock  speed  and  8- 
bit  registers,  The  vector  at  SOO  05FE  points  to  another  bank  ?£ro 
location,  that  in  turn  passes  control  to  the  ProDOS  l6  interrupt 
dispatcher.  The  imermpt  dispatcher  switches  the  processor  to  full 
native  mode  (including  higher  dock  speed)  and  then  polls  the 
user-installed  interrupt  handlers.  When  the  interrupt  has  been 
serviced,  ProDOS  16  returns  to  emulation  mode  and  passes 
control  back  to  the  built-in  interrupt  handler. 

Figure  8-3  is  a  simplified  picture  of  what  happens  when  a  device 
generates  an  interrupt  that  is  handled  through  a  ProDOS  16 
interrupt  handler. 


From  built-in 
Interrupt  handler 


UHf  tnt«rrupt  vector 
Cl3f  B  in  Banit  SOO 


JMP 


Poil  each  handler 

In  sequence; 
wtil  one  accept 
the  Interrupt? 


ProDOS  16  Interrupt 

Dispatcher 

Switch  to 

full  native 

mode 

RTLbOCltto  ProDOS  16 
interrupt  Dispatcher 
(then  RTI  bock  to 
buftt-in  interrupt  handier) 


JSL 

User-Installed 

 k- 

hondler 

I  if  none  ciolms  it 

Unclaimed  interrupt 
Cf  atal  error) 

Figure  8-3 

Interrupt  hardting  through  ProDOS  16 
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ProDOS  16  supports  up  to  16  user-installed  interrupt  handleis. 
When  an  interrupt  occurs  that  is  not  handled  hy  firmware, 
ProDOS  16  transfers  control  to  each  handler  succes-sivdy  uniH 
one  of  them  claims  it.  There  is  no  grouping  of  interrupts  into 
classes;  their  priority  rankings  are  refiected  only  by  Ihe  order  in 
which  they  are  polled- 

If  you  write  an  interrupt  handler  to  nin  under  ProDOS  l6,  note 
these  conventions: 

□  Your  liandler  will  gain  control  with  the  machine  in  full  nafite 
mode  (e,  m,  and  x  =  0),  with  a  fast  clock  speed. 

□  Interrupts  will  be  disabled.  Do  not  re  enable  intermpts  from 
within  your  intermpt  handler, 

□  The  handler  must  exit  with  an  RTL  instrucUon.  The  machine 
should  again  be  in  full  native  mode,  at  fast  speed,  The  cany 
flag  must  be  cleared  C  =  0)  if  the  interrupt  was  serviced,  andsei 
C  -  1>  if  it  was  not— that  is  how  ProDOS  l6  knows  whether  or 
not  your  handler  has  claimed  the  interrupt. 

To  make  your  interrupt  handler  active,  install  it  with  ihe  ProDCK 
16  ALLOC_[NTERRUPT  call.  To  remove  it,  use  the  DEALLOC 
INTERRUPT  call.  Be  sure  to  enable  the  hardware  generating  the 
internipt  only  q/ler  the  routine  to  handle  it  is  allocated;  likewise, 
disable  tJie  hardware  be/ore  the  routine  is  deallocated 


User  tool  sets 

The  Apple  IIGS  Toolbox  is  quite  extensive  and  provides  a  grfiit 
deal  of  programming  convenience;  there  are  over  800  separate 
routines  that  you  can  call  from  your  applications.  Furthermore, 
because  of  the  flexibility  of  the  Tool  Locator  system,  your 
application  is  not  restricted  to  even  this  large  number  of  tool 
calls.  In  addition  to  the  system  loo!s  (provided  by  Apple),  you 
can  write  and  install  your  own  tool  sets,  called  mer  tools. 

Writing  and  installing  user  tool  sets  is  fully  documented  under 
"Writing  Your  Own  Tool  Set"  In  the  App!e  IIGS  Toolbox 
Reference.  We  won't  repeat  that  information  here,  beyond  listing 
these  few  main  points: 
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□  The  open-ended,  flexible  nature  of  ihe  Tool  Locaior  is  what 
makes  it  possible  lo  add  your  own  lool  sets.  The  Tool  Locator 
requires  no  fixed  UOM  location  and  few  Tixed  RAM  locations, 
so  it  may  easily  modify  its  data  structures  lo  incorporate  new 
tool  seiS- 

□  Each  lool  set  is  assigned  a  permanent  tool  number.  System 
tools  are  assigned  numbers  by  Apple;  you  can  assign  your  ow 
numbers  lo  user  tool  sets  that  you  create.  Assignment  starts  at 
and  continues  as  successive  integers  (2,  5,     and  so  forth). 
Tabic  a-2  lists  the  presently  defined  system  tool  numbers. 


Table  6-2 

Tool  sot  numbers 


Hexodscimal 

I^UI  1  IV 

SDl 

1 

Tool  locator 

$02 

2 

Memory  Manager 

$03 

3 

Miscellaneous  Tool  Set 

$04 

4 

QuickDraw  11 

$05 

5 

Desk  Manager 

$06 

6 

Event  Manager 

$07 

7 

Scheduler 

$08 

8 

Sound  Tool  Set 

$09 

9 

Apple  Desktop  Bus  Tool  Set 

SOA 

10 

SANE 

SOB 

11 

Integer  Math  Tool  Set 

SOC 

12 

Text  Tool  Set 

SOE 

14 

Window  Manager 

$0F 

15 

Menu  Manager 

$10 

16 

Control  Manager 

$11 

17 

System  Loader 

$12 

18 

QuickDraw  U  Auxiliary 

$13 

19 

Print  Manager 

$14 

20 

LineEdit  Tool  Set 

$15 

21 

Dialog  Manager 

$16 

22 

Scrap  Manager 

S17 

23 

Standard  File  Operations 

S19 

25 

Note  Synthesizer 

$1A 

26 

Note  Sequencer 

$1B 

27 

Font  Manager 

$1C 

28 

List  Manager 
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□  Each  routine  within  a  too]  set  is  assigned  a  permanent! 
funciion  number  Function  numbers  start  at  1  in  each  tt.., 
and  continue  as  successive  integers.  Certain  standard  alls  u 
be  present  in  every  tool  set,  and  so  certain  hjncUon  numben 
are  reserved.  TabJe  8-3  lists  them.  See  the  toolbox  mmujlfa'' 
explanations  of  what  each  function  must  do. 

□  There  are  some  general  r\jles  and  design  consideraiions  that 
tool  sets  must  follow.  For  example,  tool  sets  receive  control  iji 
full  native  mode;  they  rtiusi  obtain  any  needed  work  space  froai 
the  Memory  Manager;  they  must  provide  some  sort  of  intecnipt 
environment;  and  they  must  restore  the  caller's  operating 
environment  before  returning  control  to  the  caller,  See  the 
Apple  IIGS  Toolbox  Rsference  for  details  on  these  and  oibei 
design  requirements. 

Table  8-3 

Standard  tool  set  rouffne  numbora 


FuncNum 

Description 

1 

Boot  initialization 

2 

Application  startup 

3 

Application  shutdown 

4 

Version  information 

5 

Reset 

6 

Status 

7 

Reserved  for  future  use 

a 

Reserved  for  future  use 
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This  is  as  far  as  we  can  take  yoa  in  this  book.  For  your  nexL  step, 
spread  out  your  developmenc-environment  manuals,  Apple  IIGS 
technical  manuals,  and  the  Apple  IIGS  ToolBox  Reference,  2nd 
play  with  HodgePodge  on  the  Apple  IIGS  or  start  your  own 
applicaton.  In  parting,  we'll  give  you  a  few  hints^ — mostly 
summaries  of  the  ideas  presented  throughout  the  book^ — and  wd 
mention  two  organizations  that  can  help  you  become  a  successM 
Apple  IIGS  developer. 


Modify  Hodgepodge 

The  easiest  way  to  get  started  on  your  own  desktop  appUcauot! 
may  be  10  take  HodgePodge  and  modify  it  incrementally. 
Recompile  it  and  run  it  after  each  small  change  to  see  how  vair 
changes  look  Cor  even  if  they  work). 

You  might  begin  by  modifying  text  within  dialog  boxes,  or 
changing  tlie  names  of  menu  titles  or  items.  As  you  become  i 
little  braver,  try  adding  (or  removing)  menus  or  menu  items,  and 
adding  (or  removing)  the  subroutines  called  from  those  me™ 
items.  Remember  that  adding  an  item  to  a  menu  wiU  lequire 
changing  the  routine  DoMenu  as  well  as  changing  the  rnenu 
definitions  themselves — not  to  mention  writing  a  subroutine  that 
does  something  when  the  menu  item  is  selected. 

Soon  you'll  become  more  ambitious,  and  you  can  branch  in 
almost  any  direction,  Add  a  routine  that  plays  a  song  when  ailed, 
Define  a  new  window  type,  perhaps  even  one  that  permits  tlic  usa 
to  draw  or  type  into  it.  Define  a  file  type  for  that  window  t)'pc,  id 
allow  the  user  10  save  results  to  disk.  Give  HodgePodge  the  abSity 
to  cut  and  paste  to  and  from  the  Clipboard,  and  display  the 
Clipboard  window.  Play  with  menu-  and  window-frame  colors. 

Your  imagination  is  your  only  real  constraint.  Have  fun  and  I 
challenge  your  limits;  the  Apple  HGS  is  a  willing  partner  in  this 
adventure. 
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Design  your  program  carefully 

We've  discussed  design  consideraiions  for  Apple  IIGS  desktop 
applicaiions  throughout  ihe  book,  bui  some  in  particular  are 
worth  repealing.  As  you  work  on  your  own  programs,  either  by 
modifying  Hodgepodge  or  starting  from  scratch,  keep  these 
points  in  mind: 

■  Follow  the  Human  InterJace  Guidelines;  I'ollow  the  underlying 
concepts,  as  well  as  the  surface  implementation,  of  the 
guidelines.  They  describe  a  tested  and  proven  interface, 
familiar  and  friendly  to  millions  of  users.  If  you  go  beyond  the 
guidelines,  make  it  a  natural  extension. 

■  Design  data  structures  before  writing  code;  Your  menus, 
windows,  controls,  dialog  boxes,  and  alerts  influence  program 
structure  so  strongly  that  they  should  be  carefully  planned  and 
defined  at  the  beginning.  You'll  save  yourself  wasteful  rewriUng 
and  awkward  patching  if  your  code  organization  flows  naturally 
from  the  design  of  your  data  structures, 

■  Test  for  errors!  Make  it  a  habit  to  put  error-testing  code  after 
toolbox  calls.  It  can  help  inform  the  user  and  can  keep  your  pro- 
gram from  doing  harmful  things  to  the  user's  system  or  data. 

■  Save  and  restore:  When  a  subroutine  accesses  the  desktop,  it 
may  not  always  know  the  exact  state  of  things.  Note  that  many 
HodgePodge  routines  start  with  a  GetPort  call  to  save  the 
current  state  of  the  desktop,  and  end  by  restoring  the  desktop 
(with  a  SetPort  call).  It's  another  good  habit  to  get  into. 

■  Lock  handles  while  In  use:  If  your  program  has  allocated  a 
piece  of  memory  accessed  by  a  handle,  be  sure  to  lock  it  just 
before  using  it.  A  lot  of  memory  errors  are  caused  by  trying  to 
access  data  that  has  been  moved. 

■  Unlock  handles  when  not  In  uses  Don't  prevent  the  Memory 
Manager  from  doing  its  job. 

■  Dispose  handles  when  finished:  Don't  prevent  the  Memory 
Manager  from  doing  its  job. 

■  Make  It  easy  to  translate:  If  you  want  to  appeal  to  international 
markets,  remember  to  place  in  one  or  more  individual  data 
areas  all  text  that  is  to  be  displayed,  so  that  it  may  be  found 
and  modified  easily, 

•  Design  for  "Undo";  Consider  including  a  facility  that  allows  the 
user  to  reverse  his  actions  to  undo  a  mistake.  Your  customers 
will  be  eternally  grateful. 
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Join  APDA 

If  you  are  already  a  member  of  the  Apple  Programmer's  ana 
Developer's  Associaiion  (APDA).  you  know  ihat  it  is  the  fasiesE 
way  to  get  the  most  recent  software,  documentation,  and  other 
information  of  interest  to  developers.  If  you  are  not  a  mambcf, 
It  s  easy  to  join, 

APDA  is  a  membership  organizaElon  for  both  professional  and 
advanced  amateur  programmers  and  developers.  It  was  founded 
by  Apple  Computer  and  the  A.P.P.L.E.  Co-op  near  Seatde, 
Washington;  its  purpose  is  to  publicize  and  distribute 
programming  tools  and  Eechnical  documentation  for  Apple 
computers. 

APDA  serves  as  a  "one^stop  shopping  center.-  It  offers  both 
finished  products  from  Apple  and  other  vendors,  and  prerelease 
versions  of  many  Apple  development  tools  and  documenis.  Some, 
smaJl-volume  products.  noE  suitable  for  the  retail  market  are 
available  only  through  APDA,  Other  products,  scheduled  for  the 
retail  market,  are  offered  through  APDA  in  prerelease  vtm.  oa 
an  aa-is' (no  support)  basis. 

If  you  join  APDA,  you  will  receive  quarterly  catalogs  (and  jh 
frequent  updates)  of  the  available  material  for  both  Apple  U  and 
Macintosh  development.  Membership  is  open  to  all  interested 
parties.  Yearly  dues  are  $20.00. 

Write  to 

Apple  Programmer's  and  Developer's  Association 
290  SW  43rd  Street 
Eenton,  WA  98055 

(206)251-6548 


Become  an  Apple  Developer 

If  you  are  a  developer  with  a  product  soon  to  reach  the 
comrnercial  markeE,  you  may  want  to  become  an  Apple  Certifietl 
Developer.  As  a  Certified  Developer,  you  will  receive  monthly 
mailings  including  a  newsletter,  Apple  11  and  Macintosh  Techdd 


Notes,  pertment  Developer  Program  informadon.  and  all  the 
^test  news  relating  to  Apple  products.  You  will  have  access  Eoour 
Developer  Hotline  for  general  developer  informadon 
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Once  you  are  certified,  Apple's  Developer  Technical  Support  staff 
can  provide  technical  assistance  during  your  product's  evolution. 
Our  Technical  Support  engineers  will  answer  your  development 
questions  within  24  hours  by  electonic  mail. 

The  Certified  Developer  program  is  for  professional  hardware 
and  software  developers  who  plan  to  have  a  finished  commercial 
product  within  18  months.  If  you  fit  this  description  and  are 
interested,  please  write  for  an  application.  You  will  need  to  submit 
information  on  previous  products  and  your  present  business  plan 
along  with  your  completed  application. 

Write  to 

Developer  Programs 

Apple  Computer,  Inc. 

20525  Mariani  Avenue,  M.S.  27W 

Cupertino,  California  95014 

(408)  973-4897 


Licensing  Apple  software 

If  the  software  you  write  uses  all  or  part  of  some  Apple  software 
(such  as  ProDOS  l6  or  the  Apple  IIGS  Toolbox),  you  will  need  to 
license  the  use  of  that  software  from  Apple  Computer.  You 
needn't  license  any  parts  of  HodgePodge  you  use,  but  you  will 
need  to  license  any  system  software  that  accompanies  or  is 
incorporated  into  your  application, 

A  modest  yearly  fee  authorizes  you  to  use  Apple  software  in  your 
product.  There  are  no  royalties.  Please  contact 

Software  Licensing 

Apple  Computer,  Inc. 

20525  Mariani  Avenue,  M.S.  28B 

Cupertino,  CA  95014 

Attn;  Software  licensing  Program 

(408)  973-4667 
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Appendix  A 


Converting  Macintosh 
Programs  to  the  Apple  IIgs 


rf  you  have  written  a  desktop  application  for  the  MacintosJi, 
may  be  able  to  convert  it  to  run  on  the  Apple  IIGS  wiihout 
completely  rewriting  it.  On  a  conceptual  level,  the  task  should] 
rather  simple— after  all,  program  organization  and  toolbox 
capabilities  are  similar  for  both  computers.  But  when  it  con 
implementation,  there  are  many  differences  that  require  caj, 
attention  to  details  of  coding.  This  appendix  notes  some  of 
details  to  keep  in  mind  when  converting  Macintosh  progfiiiml 
the  Apple  IIGS. 


High-level  languages 


Programming  in  a  high-level  language  can  insulate  you  from 
many  of  the  differences  among  machines.  However,  the 
individual  toolbox  calls  are  different  enough  between  the 
Macintosh  and  the  Apple  liGS  that  in  most  cases  it  will  not  \xL 
possible  jus:  to  recompile  Macintosh  code  and  expect  it  to  ma- 
the  Apple  II GS. 
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The  best  approach  is  probably  to  regard  the  conversion  process 
algoriihmicaliy,  rather  ihan  literally.  In  other  words,  don't  expect 
that  you  will  be  able  to  drop  a  whole  program  or  even  any  one 
routine,  unchanged,  into  an  Apple  IIGS  program.  Use  your 
Macintosh  program's  organization  as  a  framework  into  which  to 
place  individually  converted  routines.  Even  though  most  of  the 
organization  and  much  of  the  original  code  can  be  translated 
exactly,  you'll  have  to  locate  those  statements,  calls,  and  structures 
that  arc  incompatible  with  the  Apple  IICS  environment. 

This  doesn't  necessariiy  mean  pouring  over  the  source  code  line- 
by-line.  In  general,  you  might  be  able  to  port  well-behaved  high- 
level  code,  just  by  carefully  locating  and  modifying  tool  calls  and 
any  code  that  accesses  toolbox  data  structures. 

Of  course,  if  you  have  a  routine  thai  makes  no  tool  calls,  accesses 
no  tool  structures,  and  otherwise  makes  no  Macintosh-speciric 
assumptions,  you  may  indeed  be  able  to  convert  it  simply  by 
recompiling  it. 


Assembty  language 

Approaching  the  conversion  process  algorithmlcally  rather  than 
liieraily  is  even  more  critical  when  converting  programs  written  in 
assembly  language.  Besides  toolbox  differences,  you  are  faced 
with  fundamentally  different  miaoprocessor  architectures  and 
instruction  sets,  very  different  memory  maps,  and  a  host  of  other 
low-level  differences  between  the  two  types  of  computer.  The  only 
possible  aproach  is  to  think  of  your  Macintosh  program  as  an 
organizational  shell  in  which  every  routine  will  need  extensiv^e 
revision  to  convert  correctly. 

Here  are  just  a  few  of  the  differences  to  keep  in  mind. 

■  Registers:  The  65816  does  not  have  nearly  the  number  of 

registers  that  the  680Q0  has,  so  you  will  have  to  store  more  of 
your  variables  in  memory — usually  local  memory  (direct  page). 

■  Direct  page:  Direct  page  is  an  Apple  UGS  concept  that  can  be 
very  useful,  especially  if  you  are  constructing  tables  In  memory 
and  accessing  them  by  offsets.  If  your  Macintosh  program 
allocates  such  data  structures  on  the  heap,  you  can  gain 
efficiency  by  putting  them  onto  the  Apple  IIGS  direct  page. 
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Stack;  Your  stack  on  (he  Apple  IIGS  is  likely  to  be  smaller  th«i, 
what  you  arc  used  to  on  the  Macintosh,  More  of  your  v; 
and  data  stmciurcs  will  be  allocated  in  otlier  pans  of  mernol 

Memory  space  and  segmentation;  Your  program  imy  have  lo 
run  in  less  space  on  an  Apple  IIGS  than  ii  may  be  used  to  oni 
Macintosh,  Therefore,  segmentaiion  can  be  very  importauL 
Break  the  program  into  segments,  and  use  as  many  dynamic 
segments  as  possible. 

Video  display:  The  Apple  lies  offers  you  two  different  Super 
HiTles  graptiics  modes — 320  and  640  pbtels  across.  Both  use 
color,  but  neither  has  square  pixels. 


Toolbox  differences 

If  you  compare  the  Macintosh  and  Apple  IIGS  toolboxes,  ycyul! 
see  that  many  routines  have  identical  names  and  function  in  the 
same  way.  Many  others  do  not,  however,  so  watch  out  for 
difTerenccs  when  using  the  tools.  In  particular^  the  required 
parameters  and  the  order  of  the  parameters  may  differ  btt 
the  Macintosh  and  Apple  IIGS  versions  of  a  particular  call,  Be  i 
sure  to  look  up  each  routine  in  the  Apple  IIGS  Toolbox  Refei 
before  using  it. 

Some  groups  of  tool  calls  are  more  alike  than  others,  For 
example,  many  QuickDraw  calls  are  identical  or  very  simflari 
both  environments.  Thus,  graphic  routines  might  be  relatively  I 
simple  to  translate.  On  the  other  hand,  calls  that  direcdy  acc 
or  manipulate  memory,  such  as  Memory  Manager  calls  and 
handle  manipulations,  can  operate  very  diflerently  in  the  two 
environments — even  when  they  look  the  same.  Be  careful. 

Also  keep  in  mind  that  the  records  that  describe  toolbox 
structures  such  as  GrafPorts  and  controls  are  different.  Fields'! 
exist  in  one  environment  may  not  be  in  the  other.  So  be 
particularly  careful  if  you  access  data  structures  direcdy. 

Some  specific  recommendations  on  how  to  handle  toolbai 
differences  follow. 
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Resources 


PoKOl  Ho dg 9 Podge  Is  listed  In 
Appendix  G.  FurtherrTiOre. 
ndivldua!  rOLrtines  are  listed  and 
[Jescflbed  thioughout  the  book. 
iBeToble2-l, 


To  a  Macintosh  programmer,  the  term  resource  means  something 
much  more  specific  than  a  useful  item.  Kesources  are  certain 
types  of  data  structures,  easily  accessible  by  the  programmer,  that 
help  to  separate  code  from  static  data  and  make  program 
modification  simpler. 

The  Apple  IIGS  has  no  predefined  structures  like  resources,  and  no 
Resource  Manager  or  resource  editors  for  manipulating  tliem.  So, 
in  conversion,  you  will  have  to  move  your  resources  from  the 
resource  fork  of  your  file  into  your  program  code,  eidier  as 
separate  data  segments  or  files,  or  merged  into  the  execution 
stream,  The  Pascal  version  of  the  sample  program  HodgePodge 
shows  several  ways  to  do  this: 

■  Icons:  You  can  define  your  icons  by  directly  creating  a  pattern 
in  memory,  as  Hodgepodge  does  with  the  Apple  icon  in 
InitGlotaala  (file  HP. PAS). 

■  Text  strings;  Instead  of  a  string  or  string  list  resource,  you  can 
define  your  strings  in  initialization  routines  (as  HodgePodge 
does  with  its  menu  strings),  or  in  the  individual  routines  in 
which  ihey  are  needed  (as  HodgePodge  does  with  prompt 
strings  in  the  Standard  File  dialog  boxes). 

Remember,  keeping  all  your  strings  easily  accessible  will  make 
the  program  more  convenient  to  translate  or  otherwise  modify. 

■  Window  and  dialog  box  templates:  The  templates  (DLOG, 
WIND,  ALRT,  and  DITL  resources  on  the  Macintosh)  used  to 
define  your  windows  and  dialog  boxes,  and  the  controls  and 
items  within  them,  must  be  defined  within  the  body  of  your 
Apple  IIGS  code. 

Each  time  it  opens  a  window,  HodgePodge  defines  and 
initialises  a  parameter  list  that  controls  the  window's 
appearance  (part  of  the  routine  DoTheOpen  in  window. pas). 
When  it  creates  an  alert  box,  it  calls  a  routine 
(MakeATemplate  in  DIALOG, f  AS)  that  defines  the 
characteristics  of  an  alert  box  and  two  items  within  iL 

Other  resources  in  your  Macintosh  program  will  need  to  be 
converted  similarly. 


Toolbox  differences  235 


1 


TaskMasfer  or  GetNextEvent? 

nie  Apple  IIGS  offers  al  least  one  very  useful  event-handling 
capability  not  yet  available  on  the  Macintoshr  TaskMasm. 
TaskMaster  automatically  handles  many  standard  events  for 
standard  types  of  windows-^resizing,  dragging,  scrolling,  uptUlijjg 
and  activating,  and  so  on. 

On  the  other  hand,  the  Apple  IIGS  also  supports  "normal"  event- 
handling  with  Geth-'extEvent,  just  as  on  the  Macintosh.  So  it  miglj 
seem  more  efficient  to  keep  that  same  GetNextEvent  organization 
when  converting  an  existing  Macintosh  program. 

Usually  it  is  not.  Unless  your  program  constructs  unconventional 
windows  or  handles  them  in  an  unusual  manner,  ii  is  probably 
best  to  change  from  GetNextEvent  to  TaskMaster  when  making  tk 
conversion.  Using  TaskMaster  may  allow  you  to  eliminate  enliie 
routines  from  your  progam,  routines  that  would  otherwise  need 
individual  attention  to  convert  correctly. 

Hodgepodge,  for  example,,  has  no  update  routine,  no  acUvate 
routine,  no  scrolling  procedure,  no  window-dragging  or  -resijing 
rouUnes,  and  yet  it  supports  windows  that  do  all  those  things.  It 
may  greaUy  simplify  your  conversion  to  switch  to  TaskMaster. 


QuickDraw  II 

QuickDraw  II  on  the  Apple  IIGS  is  quite  similar  to  QuickDraw  on 
the  Macintosh,  apart  from  extensions  to  suppon  Apple  IIGS  color 
display.  However,  keep  the  following  in  mind: 

□  The  conceptual  drawing  space  for  QuickDraw  H  has  boundary 
coordinates  -16K,  -16K,  i6K,  16k,  compared  to  -32K,-32K  and 
32K,32K  on  the  Macintosh. 

Q  QuickDraw  II's  pixel  images  are  similar  to  Macintosh 

QuickDraw's  bit  images,  but  pixels  are  described  by  more  than 
one  bit  each.  Bit  images  such  as  icons  will  have  to  be 
converted  to  pixel  images,  with  either  two  or  four  bits  per  piid 
Icons  arc  not  as  restricted  on  the  Apple  liGS  as  they  are  on  the 
Macintosh.  Besides  having  color,  they  may  be  of  arbitrary 
height  and  width,  rather  than  32  pixels  (bits)  on  a  side. 
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□  You  won't  need  to  change  most  drawing  commands — your 
black-and-whiie  Maciniosh  drawings  will  convert  directly  to 
white- an d-black  drawings  on  the  Apple  IIGS  screen. 

There  will  be  some  change  in  aspect  ratio  of  images  and  drawn 
objects  Jn  transferring  lo  the  Apple  IIGS  screen,  and  significant 
changes  in  overall  size — Super  Hi-Res  pixels  are  not  square  and 
are  significantly  larger  than  Macintosh  screen  pixels. 

□  Text  drawing  and  text  measurement  on  the  Apple  IIGS  are 
similar  to  their  treatment  on  the  Macintosh.  The  Apple  IIGS 
font  definition  is  similar  to  that  of  the  Macintosh,  and  a  simple 
conversion  algorithm  allows  the  IIGS  to  use  any  font  developed 
for  the  Macintosh.  Most  Macintosh  QuickDraw  text  calls  are 
duplicated  precisely  in  QuickDraw  II. 

Some  calls  have  been  added  to  handle  the  est  ring  data  type 
(a  sequence  of  characters  terminated  by  a  0  byte). 

QuickDraw  II  does  not  scale  text — the  Font  Manager  does.  In 
general,  the  interaction  between  the  Apple  IIGS  Font  Manager 
and  QuickDraw  11  is  different  from  the  dose  relationship 
between  the  Font  Manager  and  QuickDraw  on  the  Macintosh. 
Font  selection  on  the  Apple  IIGS  requires  a  little  more  care 
than  on  the  Macintosh. 


File  system  differences 

ProDOS  l6  is  the  Apple  lies  operating  system  for  desktop 
application.?.  There  are  ProDOS  l6  calls  equivalent  lo  most 
Macintosh  File  Manager  calls,  but  some  parameters  are  different 
or  are  used  differently.  If  your  Macintosh  application  makes  File 
Manager  calls,  they  will  have  to  be  translated  to  ProDOS  16  calls. 

On  the  other  hand,  if  your  program  is  written  in  a  high-level 
language  and  uses  only  that  language's  file  access  facilities,  you 
might  not  have  to  do  any  translating  ac  all.  On  recompiling  under 
a  IIGS  development  environment,  your  file  calls  will  be  translated. 

As  noted  under  "Resources"  earlier  in  this  appendix,  files  do  not 
have  separate  resource  and  data  forks.  Data  stored  as  resources  in 
your  Maciniosh  files  will  have  to  be  redefined  and  stored  as 
standard  ProDOS  l6  files. 
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If  your  program  handles  all  its  file  access  through  Standard  File 
Operations,  it  will  not  have  to  manipulate  pathnames  explicitly. 
Just  as  on  the  Macimosh,  the  Standard  File  Operations  Tool  Set 
on  the  Apple  IIGS  lakes  care  of  all  that.  But  if  you  do  access  files 
by  name,  please  note  these  differences  from  the  Macintosh  file 
system: 

□  Filenames  under  ProDOS  16  are  more  restricted  than  on  the 
Macintosh,  Only  the  characters  A~Z,  1-9,  and  the  period  (.)  an 
permitted,  and  the  maximum  length  is  15  characters. 

□  ProDOS  16  permits  you  to  define  up  to  9  prefixes,  for 
convenient  simultaneous  access  to  files  in  several  different 
subdirectories. 

□  ProDOS  16  uses  a  hierarchical  file  system,  in  which  files  are 
grouped  into  subdirectories  and  accessed  by  pathname.  The 
present  Macintosh  file  system  is  also  hierarchical,  but  if  you 
have  an  early  Macintosh  program  written  for  \he.  Jlat  file 
system,  you  may  have  to  modify  it  to  account  for  pathname 
instead  of  just  filenames. 


Other  toolbox  differences 

As  you  get  involved  in  the  conversion  process,  you  will  of  course  i 
discover  many  otlier  differences,  some  subOe  and  some  obvious,] 
between  the  Macintosh  and  Apple  lies  toolboxes.  There  are  far 
too  many  to  list  in  this  appendix,  but  here  is  a  sample: 

■  Memory  Manager:  The  Apple  IlGS  Memory  Manager  is 
conceptually  very  similar  to  the  Macintosh  Memory  Manager,] 
However,  because  of  the  65C8I6  microprocessor  and  the 
architecture  of  the  Apple  IIGS,  the  Apple  liGS  Memory 
Manager's  calls  are  very  different,  and  its  internal  data 
structures  totally  different,  from  those  of  the  Macintosh.  Pay 
extra-close  attention  to  converting  Memory  Manager  calls  and 
manipulating  its  data  structures  such  as  pointers  and  handles. 

■  Window  Manager/Control  Manager:  Windows  and  controls  ( 
be  handled  differently  in  several  ways,  largely  because  of  the 
Window  Manager  routine  TaskMaster.  The  Apple  IIGS  has 
window  types  that  include  scroll  bars  (frame  scroll  bars) 
manipulated  automatically  by  TaskMaster.  The  use  of  frame 
scroll  bars  greatly  simplifies  window  handling. 
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■  Frame  scroll  bars:  If  you  use  TaskMaster  and  have  it  manipulate 
frame  sCfoH  bars,  remember  ihat  ihe  scroll  bars  are  part  of  the 
window  frame,  not  ihe  content  region.  That  is,  unlike  standard 
scroll  bars  on  a  Macintosh  window,  ihey  are  outside  the 
window's  port  rectangle.  That  may  affect  your  dipping  and 
drawing  commands. 

■  Desk  Accessories:  If  you  are  convening  a  Macintosh  desk 
accessory,  it  will  become  a  new  desk  accessory  on  the  Apple 

IIGS. 

■  Standard  File  Operations:  The  DiJi  button  on  the  Apple  IIGS 
works  differently  from  the  Drive  button  on  the  Macintosh. 
When  a  user  clicks  the  Disk  button.  Standard  File  first  looks  at 
the  disk  in  the  same  drive  the  current  disk  is  in.  If  the  current 
disk  is  no  longer  in  that  drive,  the  disk  in  that  drive  becomes 
the  current  disk,  If  the  current  disk  is  still  there,  the  Disk  button 
moves  to  the  next  disk  in  the  ProDOS  chain.  The  Disk  button 
works  this  way  because  a  user  can  change  disks  without  the 
system's  knowledge. 

■  Printing:  On  the  Apple  IIGS,  the  Choose  Printer  function  is 
part  of  the  Print  Manager,  rather  than  part  of  the  Chooser  desk 
accessory  as  on  the  Macintosh.  To  support  printing,  you  will 
need  to  add  a  Choose  Printer  menu  item  to  the  File  menu,  and 
create  a  short  routine  to  handle  it. 
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Appendix  B 


Enhancing  Standard 
Apple  II  Programs 


If  you  have  wricten  a  ProDOS  8-based  program  for  a  standard 
Apple  II  computer  C64K  Apple  II  Plus,  Apple  He,  or  Apple  11*0,  yoe 
should  be  able  la  run  iE  without  modificalion  on  the  Apple  IIGS. 
The  only  noticeable  difference  will  be  its  faster  execution  betauw 
of  the  greater  dock  speed  of  the  Apple  IlGS — and  even  that 
difference  can  be  eliminaEcd  if  you  wish.  However,  the  program 
will  not  be  able  to  take  advantage  of  any  advanced  Apple  IIGS 
features  such  as  its  large  memory,  the  toolbox,  the  mouse-based 
interface,  and  the  new  graphics  and  sound  abilities. 

This  appendix  discusses  some  of  the  ba^ic  alterations  you  can 
make  to  upgrade  a  ProDOS  8  application  for  various  execution 
modes  on  the  Apple  IIGS,  Depending  on  the  program's  size  and 
stmcture  and  the  new  features  you  wish  to  install,  those  changes 
may  range  from  minor  to  drastic. 

High-level  languages-  This  discussion  is  primarily  about 
assembly-language  programs.  If  you  have  a  standard  Apple  E 
program  written  in  a  compiled  BASIC  or  other  high-level 
language,  converting  it  to  mn  in  native  mode  on  the  Apple  IIGS 
may  require  nothing  more  than  recompiling  it  on  an 
equivalent  Apple  IIGS  development  system.  Accessing  the 
toolbox  may  then  be  as  easy  as  adding  the  calls  to  your 
original  source  code. 
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Conceptual  differences 

For  ihe  purpose  of  program  conversion,  there  are  perhaps  three 
main  areas  of  difference  between  traditional  Apple  II  computers 
and  the  Apple  II CS: 

■  Hardware  exeaitjoit  modes:  The  65Cai6  microprocessor 
executes  in  both  native  mode  and  6502  emulation  mode.  In 
fact,  there  are  at  least  three  modes  to  consider: 

□  Emuladon  mode  (e  flag,  m  flag,  and  x  flag  seQ.  The 
processor  functions  like  a  6502. 

□  Native  mode  with  the  m  flag  and  x  flag  set.  The  processor 
has  all  65C816  features,  but  the  accumulator  and  index 
registers  remain  8  bits  wide. 

o  Full  native  mode  (e  flag,  m  flag,  arid  x  flag  cleared).  All 
65C816  features  are  available,  and  the  accumulator  and 
index  registers  arc  l6  bits  wide. 

The  65816  microprocessor  adds  several  new  addressing  modes 
and  insiructions  to  those  of  the  6502.  All  6502  and  65C02 
instructions  are  still  available,  but  the  new  larger  registers  and 
relocatable  stack  and  direct  page  add  flexibility  and  power  to 
the  system, 

■  Tool  sets-.  The  toolbox  is  the  essence  of  what  makes  the  Apple 
lIGS  more  powerllil  and  convenient  than  other  Apple  II 
computers.  To  write  the  kinds  of  programs  described  in  this 
book,  you  need  access  to  the  toolbox.  Tool  calls  can  be  made 
while  in  full  native  mode  only. 

The  Apple  ncs  also  provides  a  sophisticated  loader  and  a 
software  memory  manager.  To  lake  full  advantage  of  the 
system,  you  should  write  relocatable  code,  and  request  any 
memory  you  need  through  Memory  Manager  calls.  Otherwise 
your  program  will  be  incompatible  with  other  programs  in 
memory,  such  as  desk  accessories  and  memory-resident 
utilities. 

■  Operating  systems:  The  Apple  IIGS  comes  equipped  with  two 
operating  systems;  ProDOS  6  and  ProDOS  16.  Unaltered 
standard-Apple  II  applications  can  run  on  the  Apple  IIGS  only 
under  ProDOS  B.  They  cannot  access  tool  sets  or  ProDOS  l6. 
They  can  make  ProDOS  8  calls  only  while  in  emulation  mode. 
The  ProDOS  3  global  page  is  supported,  but  again  only  in 
emulation  mode. 
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WriEing  a  hybrid  application  is  not  easy,  and  the  results  for 
toolbox  access  are  not  always  entirely  satisfactory.  You'll  need  to 
address  at  least  these  issues: 

■  Loading  RAM  patches;  If  your  program  is  self-booting  (starts  up 
directly  under  ProDOS  8)  on  the  Apple  TIGS,  ProDOS  l6  and 
the  System  Loader  will  not  have  been  activated.  Iherefore  RAM 
tool  sets  and  RAM  patches  to  the  ROM  tool  sets  will  not  be  in 
place.  There  are  several  possible  responses  to  this  problem: 

D  Do  -without  the  patches  or  RAM-based  tools. 

□  Write  your  own  ItAM-based  tool  set,  convert  it  to  ProDOS  8 
binary  format,  and  load  and  install  it  yourself.  See  "Writing 
Your  Own  Tool  Set,"  in  the  Apple  Iias  Toolbox  Reference. 

D  Allow  your  program  to  be  launched  only  from  a  ProDOS  16- 
ba^ed  finder  or  launcher,  after  the  normal  ProDOS  l6  boot 
sequence  has  loaded  all  the  RAM  patches  and  RAM  tool  sets. 

■  Switching  stacks  and  zero  pages:  You  have  a  standard  stack 
and  zero-page  available  in  emulation  mode,  but  you  also  need 
a  direct-page/stack  space  for  use  by  tool  sets  in  native  mode. 
Set  it  up  as  needed.  When  switching  from  emulation  mode  to 
native  mode  and  back,  you  must  save  the  current  value  of  the 
stack  pointer,  and  set  the  stack  pointer  to  the  proper  value  for 
the  mode  you  are  about  to  enter.  Likewise,  the  direct  register  is 
set  [o  zero  upon  entering  emulation  mode;  you  must  save  its 
value  before  switching  to  emulation  and  restore  it  upon 
returning. 

For  detailed  instructions  on  saving  and  restoring  the  proper 
environment  while  switching  execution  modes,  see  "Notes  for 
Programmers"  In  the  Apple  ifGS  Firm-ware  Reference. 

■  Staying  in  bank  $00  or  disabling  Interrupts:  Any  code  that  your 
program  calls  while  in  emulation  mode  must  be  in  bank  $00,  or 
else  interpjpts  must  be  disabled.  The  Program  Bank  register  is 
not  saved  or  restored  when  an  interrupt  occurs  in  emulation 
mode. 
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Tbe  PWEnJry  coll  Is  part  of  the 
Miscellansoijs  Tool  Set.  See  the 
App!g  IIGS  Toolbox  ffeference. 


Insert  parts  of  your  6502  code 

Because  the  65C816  processor  recognizes  the  6502  insiruction 
It  m^Y  be  possible  lo  use  significant  sections  of  your  code, 
unchanged  or  only  slightly  modined,  in  a  native-mode,  ?io' 
16-based  aj^piicaiion.  That  is,  instead  of  making  a  hybrid 
application,  you  might  write  a  new  Apple  IIGS  appIicaUon, 

save  time  by  incorporating  as  much  of  your  older,  6502-  

code  as  possible.  In  most  cases  this  option  is  far  better  than 
writing  a  hybrid  application;  it  puts  ProDOS  16  and  the  tool 
much  more  direciiy  at  your  program's  disposal. 

How  successful  you  can  be  depends  greatly  on  the  specific 
content  of  your  existing  code.  Routines  that  draw  to  the  screea 
otherwise  duplicate  the  tasks  performed  by  tool  set-s  may  not' 
worth  converting  to  native-mode  execution,  Code  that  uses 
absolute  address  references  or  that  must  itself  occupy  spedflt? 
addresses  will  be  incompatible  with  native-mode  memory 
management.  lasirucdons  that  can't  reach  everywhere  in  the 
l6-megabyte  Apple  liGS  memory  space  (such  as  JSR  rather  thtn 
JSL)  can  cause  a  lot  of  problems,  depending  on  where  your  codff? 
and  data  are  and  what  system  features  you  need  to  access. 

In  spite  of  these  and  other  problems,  it  may  be  possible  to  use 
large  portions  of  certain  types  of  6502-based  code,  relatively 
unchanged,  in  native-mode  Apple  IIGS  applicaUons.  Here  are ' 
a  few  considerations. 

■  Register  width:  In  most  cases  your  6502  code  will  require  jhofl 
C8-bit)  accumulator  and  index  registers  when  mnning  in  nadvt 
mode,  That  is,  the  m-  and  x-bits  need  to  be  set  (  =1)  when' 
e-bit  is  cleared  (  -O).  However,  see  the  next  note, 

■  Stack  manipulation:  Ttie  stack  pointer  value  is  commonly 
and  restored  wiih  the  instruction  pair  'I'SX.  ,  TXS,  If  perform 
in  8-bii  mode,  this  sequence  des  troys  the  high-order  byte  of  the 
stack  pointer.  To  be  safe,  do  alUtack  manipulation  with  16-bit 
registers. 

m  Firmware  entry  points:  Replace  all  calls  to  specific  nrmmre 
entry  pomts  with  FWEntry  tool  calls,  FWEntry  allows  you  while 
m  native  mode,  to  make  calls  to  (6502)  code  that  executes  in 
emulation  mode;  it  saves  and  restores  the  Data  Bank  and 
Direct  registers. 
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■  Data  and  buffer  allocatloru  Remove  absoluie  addresses  that 
define  your  data  buffers  or  other  entry  points.  For  example,  if 
your  program  reserves  a  4K  buffer  spaos  with  an  equate  such  as 
BUFFER  EQU  $8  000,  replace  that  with  something  such  as 
BUFFER  DS  $10 0 0,  which  reserves  a  SlOOO-byte  buffer  but 
doesn't  require  it  to  start  at  address  $8000. 

■  Input/output:  I/O  in  a  stanckrd  Apple  II  computer  takes  place 
by  accessing  locations  in  the  $Cxxx  address  space  Cl/O 
memory).  In  the  Apple  IlGS,  I/O  memory  exists  only  in  banks 
SOO,  SOI,  $E0,  and  $E1.  Therefore,  if  your  code  is  running 
anywhere  in  expansion  RAM,  it  cannot  perform  I/O  unless  data 
accesses  to  $Cxxx  are  made  in  long  addressing  mode,  to  access 
the  proper  bank. 

However,  the  timing  of  much  I/O  is  critical  and,  because  a 
long-addressing  load  instruction  takes  an  extra  cycle  to  execute, 
you  may  not  be  able  to  change  the  addressing  mode. 

One  way  around  this  is  to  set  the  data  bank  register  to  $00 
before  executing  the  I/O  instructions.  Then,  however,  any  other 
data  in  the  same  bank  as  your  code  becomes  inaccessible — but 
that  may  not  be  a  problem  in  your  particular  case. 

There  are  many  other  alternatives,  including  creative  use  of  the 
direct  page  and  isolating  timing-critical  code,  that  can  be  useful 
in  various  individual  situations.  Every  situation  is  unique — feel 
free  to  be  creative. 


Rewrite  it  to  run  under  ProDOS  16 

Modifying  your  entire  program  for  full  1 6-bit  native  mode 
operation  on  the  Apple  HCS  is  a  more  ambitious  task,  but  it  may 
well  be  worth  it  for  the  greater  number  of  features  you  can  access. 
In  order  to  run  entirely  in  native  mode,  under  ProDOS  l6  and 
with  the  tool  sets  always  available,  your  program  needs  to 
consider  at  least  the  following  points. 

■  Managing  memory:  Because  the  Apple  IIGS  supports 
segmented  load  files,  one  of  the  first  decisions  to  make  is 
whether  and  how  to  segment  the  program  (both  the  original 
program  and  any  added  parts).  First,  make  your  code 
relocatable  so  the  Memory  Manager  can  control  where  it  is 
loaded-  You'll  need  to  specify  memory-block  attributes  in 
addition  to  modifying  your  code  as  described  in  the  previous 
section,  "Insert  Pans  of  Your  6502  Code." 


Revi/rire  if  to  txin  under  ProDOS  16 
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Memory  management  under  native-mode  operation  on  Lhe 
Apple  IIGS  is  completely  different  from  stands rd-AppJe  II 
methods.  If  your  program  allocates  iLs  own  memory  space  ind 
marks  it  off  in  the  ProDOS  8  global  page  bit  map,  the 
enhanced  version  must  be  altered  so  that  it  requests  ali  nedd 
space  from  the  Memory  Manager. 

I  Converting  operating-system  calls:  For  most  ProDOS  8  calls, 
diere  is  an  equivalent  ProDOS  16  call  with  the  same  name,  Stil, 
each  call  block  must  be  modified  for  ProDOS  16,  and  cad 
parameter  block  must  be  reconstructed  in  the  ProDOS  16 
format. 

For  other  ProDOS  8  calls,  a  ProDOS  16  near-equivalent 
performs  a  slightly  different  task,  and  the  original  code ' 
have  to  be  changed  to  account  for  that. 

Yet  other  ProDOS  S  calls  have  no  equivalent  in  ProDOS  l6.  If 
your  program  uses  any  of  these  calls,  they  will  have  to  be 
replaced  as  appropriate. 

I  RemoTlng  global  page  references;  Any  access  your  origin 
program  makes  to  the  ProDOS  8  global  page  must  be  repijiced 
by  appropriate  ProDOS  l6  or  toolbox  calls. 

I  Converting  stack  and  zero  page;  Under  ProDOS  l6  in 
native  mode,  you  are  not  constrained  to  the  fixed  stack  an 
zero-page  locations  provided  by  ProDOS  8  in  eraulatioji  i 
You  may  either  let  ProDOS  l6  assign  you  a  default  IK  * 
page/stack  space,  or  you  may  define  a  direct-page/stack 
segment  in  your  object  code.  In  either  case,  the  loaden 
place  the  segment  anywhere  in  bank  $00 — you  cannot  i 
any  specific  address  to  be  within  the  space. 

Assembling!  Once  your  source  code  has  been  modified  i 
augmented  as  desired,  you  need  to  reassemble  it.  You  must' 
an  assembler  (or  compiler,  for  high-level  languages)  thai 
produces  object  fries  in  Apple  HCS  object  module  format 
<OMF);  otherwise  the  program  cannot  be  properly  linked ; 
loaded  for  execution.  Using  a  different  assembler  may  me 
that,  in  addition  to  modifying  your  program  code,  you'll : 
to  change  some  directives  to  follow  the  syntax  of  the  new 
assembler. 

If  you  have  been  using  the  EDASM  assembler,  you  wfll  notl 
able  to  use  it  to  write  Apple  IlGS  programs.  Instead,  you  _. 
the  Apple  IlGS  Programmer's  Workshop  (APW).  APW  is  a  i 
development  programs  thai  allow  you  to  produce  and  edit 
source  files,  assemble/compile  object  files,  and  link  them 
proper  OMP  load  files. 
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After  your  revised  program  is  linked,  assign  it  the  proper  Apple 
IIGS  application  file  type  (normally  SB3)  with  the  APW 
FileType  command. 


Start  from  scratch 

In  the  long  run.  this  is  the  best  alternative  in  most  cases.  Combing 
through  your  code  line-by-linc  to  make  all  the  conversions 
described  in  the  previous  sections — even  if  it  works — ^will 
probably  yield  a  product  that's  only  half  successful.  Why  not  start 
fresh,  maintaining  your  original  design  and  concepts  but  writing 
new  code  tliat  truly  takes  advantage  of  the  power  and  convenience 
of  the  Apple  IIGS? 

The  purpose  of  this  book  has  been  to  show  you  that  it  is  both  easy 
and  rewarding  to  write  desktop  applications  for  the  Apple  IIGS.  It 
has  also  shown  you  that  such  applications  have  a  structure,  an 
approach  to  the  hardware,  and  a  user  interface  that  are 
fundamentally  different  from  those  of  traditional  Apple  11 
software.  Don't  confine  yourself  unnecessarily;  a  clean  slate  is  the 
best  way  to  start.  Take  advantage  of  the  freedom  the  Apple  IIGS 
gives  you! 
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Files  on  an  Apple  IIgs 
System  Disk 


A  system  disk  is  a  3.5-inch  disk,  5.25-inch  disk,  or  hard  disk  lhat 
has  ihe  files  necessary'  for  an  Apple  IIGS  to  start  up  when  turned 
on  or  rebooted,  It  also  ha.s  any  files  needed  to  support  the 
specific  application  programs  on  the  disk.  This  appendix  shows 
you  what  files  a  system  disk  must  have. 

Because  not  ail  applications  have  the  same  needs,  not  all  sys 
disks  are  alike.  In  particular,  there  axe  complete  system  disks  an 
application  system  disks. 


Comprefe  sysfem  disk 

Every  Apple  TIGS  user  (and  programmer)  needs  at  least  one 
complete  system  disk.  It  is  a  pool  of  system  software  resources, 
and  may  contain  files  missing  from  some  application  system 
disks.  Table  C-1  Hits  the  contents  of  a  complete  system  disk. 

❖  Note:  The  word  complete  doesn't  mean  that  the  system  disk 
all  the  files  that  may  be  on  your  system  disk — only  that  it  has 
all  the  available  system  resources.  For  example,  most  system 
disks  include  files  containing  disk  utility  programs  or  finder- 
style  program  launchers.  Those  programs  aren't  considexed 
here. 


tents  of  a  complefe  sysfom  disk 


k«clorY/Flle 


Description 


PRODOS 

SYSTEM/ 
PB 
P16 

START 
LISS/ 
TOOLS/ 
FONTS/ 
DESK. ACCS/ 
DRIVERS/ 
SYSTEM. SETUP/ 
TOOL . SETUP 


ATINIT 
ATLOAD . 0 

BASIC. SYSTEM 

APPLETALK/ 


A  routine  that  loads  the  proper  operating  system  and  selects  an 
application,  both  ai  boot  time  and  whenever  an  application  quits. 

A  subdirectory  containing  the  following  files; 

The  PfoDOS  3  operating  system. 

The  ProDOS  l6  operating  system  and  Apple  IlGS  System  Loader. 

The  first  program  executed:  typically  a  program  launcher  or  finder. 

A  subdirectory  containing  the  standard  system  libraries. 

A  subdirectory  containing  all  RAM-based  tool  sets. 

A  subdirectory  containing  all  fonts. 

A  subdirectory  containing  all  desk  accessories. 

A  subdirectory  containing  printer  and  port  drivers. 

A  subdirectory  containing  system  initialization  programs. 

A  permanent  initialization  file  containing  patches  to  ROM  and  a 
program  Eo  install  them.  This  is  the  only  required  file  in  the 
SYSTEM.  SETUP  /  Subdirectory;  it  is  executed  before  any  others  that 
may  be  in  the  subdirectory. 

A  permanent  initialization  file  that  initializes  the  AppleTalk  network. 

Another  file  for  AppleTalk  intialitation. 

The  Applesoft  BASIC  system  interface  program, 

A  subdirectory  containing  files  supporting  the  built-in  Appletalk 
network  interface. 

The  complete  system  disk  is  an  800K  byte,  double-sided  3.5-inch 
disk;  the  required  files  will  not  fit  on  a  140K,  single-sided  5.25-inch 
disk.  However,  sec  "Application  System  Disks"  (next). 

When  you  boot  a  complete  system  disk,  it  executes  the  file 
SYSTEM /START. 
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The  SYSTEM.SETUP/  subdirectory 

The  SYSTEM.  SETUP/  subdirectory^  may  conlain  several  diL™, 
types  of  flies,  all  of  which  are  loaded  ai  boot  time.  They  include 
the  following. 

■  TOOLSETIIP;  This  file  must  always  be  present;  it  is  executed 
before  any  others  in  SYSTEM.  SETUP/.  TOOL.  SETUP  install 
and  initialises  any  RAM  patches  lo  ROM-based  tool  seL?  Afta 
TOOL  .  SETUP  is  finished,  ProDOS  16  loads  and  executes  the 
remaining  files  in  the  SYSTEM, SETUP  /  subdirectory,  which 
may  belong  lo  any  of  the  categories  listed  below. 

■  Pennanent  initialization  ales  Cfiletype  $86):  These  files  am 
loaded  and  executed  just  like  standard  applications  (type  $B5), 
but  ihey  are  not  shut  down  when  finished  'ITiey  also  must  hivt 
certain  characteristics: 

□  They  must  be  loaded  in  nonspecial  memory. 

□  They  cannot  permanently  allocaie  any  stack/direct-page 
space. 

o  They  must  terminate  with  an  RTL  (Return  from  subrou 
Long)  rather  than  a  QUIT. 

*  Temporary  Initialization  files  (type  $B7>  These  files  are  .„ 
and  executed  just  like  standard  applications  (type  $B3),  and 
they  are  shut  down  when  finished.  They  must  terminate  withia 
RTL  rather  than  a  QUIT. 

Although  they  are  loaded  and  installed  in  the  system  at  the  sane 
time  as  the  files  in  SYSTEM .  SETUP/,  desk  accessories  actua 
reside  in  the  subdirectory  DESK.  ACCS/.  There  are  two  typ 

■  New  desk  accessories  (type  $B8):  These  files  are  loaded 
executed.  They  arc  put  in  nonspecial  memory. 

■  Classic  desk  accessories  (type  $B9>  These  files  are  loaded 
not  executed.  They  are  put  in  nonspecial  memory. 


itig^ 


ApplicaNon  system  disks 

Each  application  program  or  group  of  related  programs  comes 
on  its  own  application  system  disk.  The  disk  has  all  of  the  syitem 
files  needed  to  run  that  application,  but  it  may  not  have  all  tl 
flies  present  on  a  complete  system  disk.  Different  applicatioa 
may  have  different  system  files  on  their  application  system  i 
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Table  C-2  shows  which  files  must  be  present  on  all  application 
system  disks,  and  which  files  are  needed  only  for  particular 
applications.  In  some  very  restricied  instances,  it  may  be  possible 
to  fit  an  application  and  its  required  system  files  onto  a  single- 
sided  O^OK)  5.25-inch  disk;  most  applications,  however,  require  at 
least  one  double-sided  (SOOK)  3.5-inch  disk. 


rabl9  C-2 

Required  contents  of  an  application  system  disk 


(Httctory/Filfi 

Required? 

PRODOS 

Yes 

SYSTEM/ 

Yes 

P3 

(Required  if  the  application  runs  under  ProDOS  8) 

P16 

Yes 

START 

(Required  if  a  START  file,  such  as  a  finder,  is  to  be  usedQ 

LIBS/ 

(Required  if  system  library  routines  are  needed) 

TOOLS/ 

(Required  if  the  application  needs  RAM-based  tools) 

FONTS/ 

(Required  if  the  application  needs  fonts) 

DRIVERS 

(Required  if  the  application  dc3es  any  printing  or  serial 

communication) 

DESK . ACCS/ 

(Required  if  desk  accessories  are  to  be  provided) 

SYSTEM, SETUP/ 

Yes 

TOOL, SETUP 


Basic, SYSTEM 
APPLETALK 


Yes 


(Required  if  the  application  is  written  in  Applesoft  BASIC) 

(Required  if  the  application  supports  printing  to  a  LaserWriter  or 
otherwise  uses  AppleTalk) 


Important 


The  files  PRODOS,  PB.  and  P16o!l  have  version  numbers.  Whenever 
It  loads  en  operating  system  (at  startup  or  wtien  launctiing  an 
application),  PRODOS  checks  the  P8  or  PI 6  version  number  against 
Its  awn.  If  the  numbers  do  nof  match,  It  Is  a  fatal  error.  Be  careful  not 
to  construct  an  application  system  disk  using  Incompatible  versions 
of  PRODOS,  P8,ond  PI 6. 


Applicotion  system  disks 
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Hodgepodge  Organization 


This  appendix  presents  three  wpics  related  to  the  Tgarvizatiofi 
the  sample  program  IlodgePoage.  ^ 

D  It  Hsts  all  Hodgepodge  routines  and  their  source  Tiles  fortH 
tnree  languages. 

□  It  diagrams  the  routines  that  execute  when  HodgePodge  opei 
a  window.  * 

□  It  discusses  and  lists  HodgePodge's  error-handling  proced' 


HodgePodge  subroutines 

Table  D-l  lists  all  HodgePodge  routines.  Column  1  list^  in  i 
alphabetical  order,  each  routine  in  the  Pascal  version.  Colum 
shows  what  source  file  each  Pascal  rouUne  is  in.  Columns  3  ar 
name  the  source  files  containing  the  equivalent  C  and  65816  ] 
assemblHanguage  routines,  Column  5  gives  the  number  of  the 
chapter  m  which  the  Pascal  version  of  each  routine  is  discus  ^ 
and  listed.  Column  6  briefly  notes  what  each  routine  does 


table  D-l 

Hodgepodge  routines  (comp[&te) 


Routine 

Pascal  file 

Cfim 

Assembly  filo 

Ustsdln ... 

Funcllon 

AddtoMenu 

MENU. PAS 

MENU.CC 

MENU. ASM 

Chap.  5 

adds  an  item 

AdjHind 

WINDOW. PAS 

WINDOW . CC 

WINDOW. ASM 

Chap.  5 

deletes  aa  item 

PAINT. PftS 

WINDOW. CC 

WItlOOM,  ASM 

Chap.  5 

which  file  to  open 

GhecttOiskError 

DIALOG. PAS 

DIALDG.CC 

DIALOG. ASM 

App.  D 

error  alert  box 

CheckFrontW 

EVEHT.PAS 

EVENT. CC 

EVENT , ASM 

App,  G 

adjusts  menu  items 

ChecitToolErroE 

DIALOG. PAS 

DIALOG.CC' 

DIALOG. ASM 

App.  D 

system  failure 

DlaableAIl 

EVENT . PAS 

EVENT. CC 

EVENT. ASM* 

App.G 

adjusts  menu  items 

Disablelcenis 

EVENT. PAS 

EVENT . CC 

EVENT. ASM* 

App.G 

adjusts  menu  items 

Dl  spF  0  ntWi  ndow 

FONT. PAS 

FONT.CC 

FONT. ASM 

Chap.  2 

calb  text-draw 

Doftboutltem 

DIALOG. PAS 

DIALOG, CC 

DIALOG, ASM 

Chap.  4 

"About"  box 

DoChooaeFont 

FONT. PAS 

FONT.CC 

FONT. ASM 

Chap.  3 

user  selects  font 

BCChooaetltem 

PRINT. PAS 

PRIHT,CC 

PRINT. ASM 

Chap.  5 

selects  printer 

DoCloseltem 

HINDOH.PA3 

WINDOW, CC* 

WIN DOW. ASM 

Chap.  2 

doses  a  window 

DoMenu 

MEND. PAS 

MENU . CC 

MEND, ASM 

Chap.  2 

dispatches  menus 

DoOpenltetn 

MENU. PAS 

WINDOW. CC 

WINDOW . ASM 

Chap.  4 

to  open  a  window 

DoPrintltem 

PRINT. PAS 

PRINT. CC 

PRINT. ASM 

Chap.  5 

calls  printing 

D&Ouitltem 

MENU. PAS 

EVENT. CC 

EVENT . ASM 

App.  G 

sets  quit  variable 

OoSaveltem 

PAIST.PAS 

WINDOW. CC 

WIN DOW. ASM 

Qiap.  5 

to  save  a  file 

FONT . PAS 

FONT.CC 

FONT. ASM 

App.  G 

toggles  menu  item 

DoSetUpItem 

PRINT, PAS 

PRINT. CC 

PRINT, ASM 

Chap,  5 

User  page-setup 

OoTheOpen 

WINDOW. PAS 

WINDOW, CC 

WINDOW. ASM 

Chap.  4 

opens  a  window 

MEND . PAS 

WINDOW, CC 

WINDOW. ASM 

App.  D 

brings  window  to  front 

DrawTopHindow 

PRINT. PAS 

PRINT. CC 

PRINT. ASK 

Chap.  5 

printing  routine 

Enable It ems 

EVENT .PAS 

EVENT.  CC 

EVENT . ASM* 

App.  G 

adjusts  menu  items 

FindMaxWidth 

*  • 

WINDOW. CC 

WIHDOH.ASM 

App.  E.  F 

sizes  font  window 

Hide A 1 1 N i n dow  s 

WINDOW . PAS 

WINDOW. CC 

WINDOW. ASM 

App.  G 

closes  windows 

HldePleaseHait 

DIALOG. PAS 

DIALOG. CC 

DIALOG. ASM 

Chap.  4 

hides  "wail"  dialog 

Hodgepodge 

HP. PAS 

flp.cc* 

HP. ASH 

Chap.  2 

main  program 

InitGlobals 

GLOBALS . PAS 

HP  ,H' 

GLOBALS. ASM" 

Chap.  2 

initializes  variables 

PAINT. PAS 

EVENT. CC 

10, ASM 

Chap.  6 

reads  a  picture  file 

Ha  in  Event 

EVENT. PAS 

EVENT, CC* 

EVENT , ASM 

Chap.  2 

main  event  loop 
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Table  D-1  (continued) 
Hodgepodge  routines  (complete) 


Bogfine 

Pascal  fite 

C1II« 

Assembly  tile 

Listed  In ... 

funcltaj 

Ksike  AT^e  mpl  a  t  & 

DIALOG. PAS 

filALOG.CC 

DIALOG. ASM' 

Chap.  4 

creates  a.lGrt  itea 

Many  Wl  ndD  i  a  1 0  g 

DIALOG . PAS 

DIALOG. CC 

DIALOG. ASM 

App,  G 

cauLio 

HountBootDisk 

DIALOG. FAS 

DIALOG. CC 

DIALOG. ASM 

App.  D 

asks  user  fc 

irdijj 

OpenPilter 

PAINT . PAS 

WINDOW. CC 

WINDOW. ASM 

Chap,  6 

alters  file  dijpli 

WINDOW , PAS 

WINDOW. CC 

WINDOW, ASM- 

Chap.  4 

to  open  a  winddj 

Faint 

PAINT. PAS 

WINDOW, CC 

WINDOW.  ASM 

Chap,  2 

calls  picture-din 

Paintit 

PAIKT.PAS 

WINDOW . CC 

WlbtDOW.  ASM 

Chiap.  5 

draws  [ 

licon 

PAINT .PAS 

EVZKT.CC 

10. ASM 

Chap.  6 

saves  a  piau 

refl 

SetCJpDefault 

PRINT. PAS 

PRINT. CC 

PRINT. ASM 

Chap,  2 

makes  print  i 

eooii 

SeXDpForAppH 

EVENT, PAS 

EVENT. CC 

EVENT. ASM 

App.  G 

adjusts  menu 

SetOpForDAW 

EVENT. PAS 

EVENT. CC 

EVEBT.ASH 

App.  G 

adjusts  menu 

SetUpMenus 

WENO.PAS 

MENU.CC 

ME«U. ASM 

Chap,  2 

makes  menvi 

SetUpWindows 

WINDOW. PAS 

WINDOW. CC* 

GLOBALS. ASM' 

Chap.  2 

sets  Size  ! 

BhowFont 

FONT. PAS 

FONT.CC 

FONT. ASM 

Chap,  3 

draws  tef 

ShowPleaaeWait 

DIALOG. PAS 

DIALOG.CC 

DIALOG. ASM 

Chap.-l 

dnses  "wait"  dialqj 

ShutDownToola 

HP. PAS 

HP.CC 

INIT.ASM 

Chap.  2 

shuts  1 

StartUpTools 

HP. PAS 

HP.CC 

INIT.ASM 

Chap,  2 

starts  all 

tool; 

■  Name  or  content  of  routine  is  sliehtly  difleretit  from 

tlie  Pascal  version. 

'  •  Does  not  exist  in  the  Pascal  version. 

Execution  sequence:  opening  a  window 

When  a  window  is  opened  in  HodgcPodge,  several  routines  ate 
called  in  sequence,  starting  with  DoOpenltem.  The  execution 
sequence  starts  out  in  the  same  way  whether  Lhe  window  to  be 
opened  is  a  font  window  or  a  picture  window. 

The  routines  involved  with  opening  a  window  are  described  in 
several  difFereni  chapters  in  this  book.  To  help  you  follow  the 
sequence,  we  diagram  the  sequence  of  subroutine  calls  here,  for 
both  font  windows  and  picture  windows. 
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Opening  a  font  window 

A  foni  window  is  opened  when  ihe  user  chooses  Display  Font 
from  the  Fonts  menu.  Thai  causes  execution  lo  pass  to  the  routine 
DoOpenltem,  which  calls  OpenWindow.  OpenWindow  first  calls 
DoChooseFont,  then  DoTheOpen  to  actually  open  the  window. 

After  OpenWindow  is  finished,  DoOpenltiem  calls  AddToMenu, 
and  tlien  execution  passes  back  to  the  main  event  loop.  See 
Figure  D-1. 

^  Note:  'ilie  dimmed  boxes  in  Figure  D-1  represent  routines 
called  to  open  a  picture  window  (Figure  D-2). 


DoChcMMsFonl 


DoOp*fiH«iTi 


OpMiWInctow  ~ 


AddToMcnu 


DoTh*Op«n 


Figure  D-1 

Execution  sequence:  opening  a  font  window 


Opening  a  picture  window 

A  picture  window  is  opened  when  the  user  selects  Open  from  the 
Hie  menu.  Just  as  when  a  font  window  is  opened,  execution  passes 
to  the  routine  DoOpenltem,  and  to  OpenWindow. 

In  tJiis  case  OpenWindow  calls  AskUser.  AsktJser  first  calls 
SFGetFile — part  of  the  Apple  lies  Toolbox,  not  Hodge  Podge, 
SFGetFile  calls  the  HodgePodge  routine  OpenFilter  while  it  is 
displaying  filenames,  Once  a  filename  is  chosen,  AskUser  calls 
LoadOne  lo  open  the  file.  OpenWindow  then  calls  DoTheOpen  to 
actually  open  the  window. 
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After  OpenWindow  is  finished,  DoOpenltem  calls  AddToMenui 
and  then  execudon  passes  back  to  the  main  event  loop.  See  Figim 
D-2. 

<•  Note:  Tlie  dimmed  boxes  in  Figure  D-2  represent  routiries 
called  to  open  a  font  window  CHigure  D-1). 


DoOpanHwn 


r 


OpenWindow  ^ 


AddToM*nu 


r  DoChCMMoFont  ^ 


SFGetFlle     —  OptnFMtr 


L 


DoTheOpan 


LoodOne 


Figure  D-2 

Executfon  sequence:  opening  a  picture  window 


Error  handling 

Hodgepodge  has  three  rouUnes  ttiai  handle  error  conditions: 
CheckToolError,  MountBootDisk,  and  CheckDiskError. 
This  section  lists  them  and  discusses  what  they  do. 


CheckToolError 

CheckToolError  is  called  only  when  the  program  is  starting;^ 
It  is  a  very  simple  error  handler,  because  any  error  it  detects  is 
made  fatal,  and  because  it  puts  up  no  message  box  for  the  user,  la 
general,  CheckToolError  cannot  put  up  a  dialog  box  because 
the  Dialog  Manager  may  not  have  been  started  when 
CheckToolError  is  called. 
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liBckTooError  Is  In  the  source  file 
lOG.PAS. 


CheckToolError  is  called  after  each  lool  stariup  call.  It  checks 
the  value  of  the  global  variable  toolErrorNum;  if  the  number  is 
nonzero  an  error  has  occurred.  In  that  case  CheckToolError 
calls  the  System  Failure  Manager,  which  puts  up  the  "sliding 
apple"  error  screen  and  halts  execution. 

^  Input;  CheckToolError  has  a  single  input  parameEcr:  an 
integer  location  number  that  specifies  what  part  of  the 
program  made  the  call,  Each  call  to  CheckToolError  passes 
a  different  integer.  The  integers  have  no  significance  or 
purpose  other  than  helping  the  programmer  locate  the  part  of 
the  source  code  that  generated  the  error. 


rocadure  CheckToolSrror  {Where:  Integecl ; 

tooLErrorSave:  Integer; 
deathMsg       ;  String; 


legin 

toolErrorSave  :=  TisolErrorNunif 
daathHsg      ;  = 

'  At  $XXXX;  Could  not  handle  error  S'; 


if  toolEirorSave  <>  0  then 
begin 

Iflt2Hax   (Where,  StringPtr  (Longint 

{^deathMagl +6) , 4J ; 
SysFailHgr   ttoolErrarSave^ deathMsgJ ; 
end; 
ind; 


{begin  CheckToolError...) 


{string  to  display} 


{save  the  error  numbar} 
{This  is  the  message  with.„J 
i-a  dummy  location  number) 

{If  there  HAS  beer,  an  error.,.) 

{...convert  Icjc,  no.  to  a  string..,) 
(...and  Insert  it  in  message) 
{Then  go  to  system  failure) 
(end  of  IF  error  nonzero) 
(End  of  CheckToolError) 


MountBootDis3(  Is  In  the  source  fie 
DIALOG.PAS, 


MountBootDisk 

MountBootDisk  is  called  during  the  loading  of  RAM-based  tool 
sets,  if  the  disk  containing  ihe  tool  sets  is  not  already  on  line. 
MountBootDislc  makes  use  of  the  Tool  Locator  routine 
TLMountVolume,  which  displays  a  dialog  box  prompting  the  user 
to  remount  the  boot  volume.  See  Figure  D-3. 
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function  MourttBootDlsk   :  integer; 

var        promptstr  :  String; 
okstr       :  String; 
canceistr  :  String; 
volStr     ;  String; 
gbvPdrams  ;  PathnameRec; 

begin 

pron^tStr        -piea^^  ^j,^  . 

ofcStr  'OK'; 
cajicelStr  :-  -Shutdown-; 
gbvParams.pathName  i-  evolStr; 

GET_BOOT_VOL   (gbvPaia™^} ; 

promptstr, volstr, 
end/  "^liStr.cancelStrJ  ; 


[begin  MountBootDisk,..} 


{String  to  appear  in  box J 
(title  of  OK  button  (=1) } 
{title  of  Cancel  button   (=2) J 
(define  pointer  to  volume  naire} 

(find  the  boot  volume  name} 
(Call  Tool  Locator's  mount -volume™}  i 
{..routine;  it  returns  the  nun^r  od 
(-.-tne  button  user  selects   (1  or  2)  1 
(End  of  ItountBootDisJt) 


Please  insert  the  disk 
/SVSTfMDISK/ 


Shutdown    )   (  qK 


Ftgure  D-3 

TLMoLrntVolume  screen  cJispJay 


noT.      >  d..|.g  box  shown  m  Figure  D-3i 

Ma         bcc.u.c  u  can.  ..u«c  .hac  Lhe  Dialog  M.nag 


CheckDiskError 


call.  ''''^        ^^^^  P^oDOS  16  cfck-acc^ 
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CheckDiskErroE  noies  whether  the  previous  operation  caused 
an  error  and,  if  so,  puts  up  a  stop  alert  and  returns  TRUE  as  the 
function  result.  Otherwise  it  just  returns  with  a  value  of  FALSE. 

•>  input.-  CheckDiskErxDr  has  a  single  input  parameter:  an 
integer  location  number  that  specifies  what  pan  of  the 
CheckDiskErro.  Is  In  the  source  fUa  program  made  the  call.  Each  call  to  checkDi  skEr  cor  passes 

DIALOG.PAS.  a  different  integer.  The  integers  have  no  significance  or 

purpose  other  than  helping  the  programmer  locate  the  part  of 
the  source  code  thai  generated  the  error. 


fuiiutian  CheckDiskError  (Where :  Intfeger) 

! Boolean; 

VBX       itemClicked  :  Integer; 

ourRl^rt     :  AleitTeiiplate; 
ourErrStr     :  Str255; 
oiaiWiereStr  :  Str255; 
ourString     :  StrZSS; 
dialtErcNura  :  Iriteger; 


(Begin  CheckDiskError-.-) 

(which  button  user  clicks) 
{defined  in  DIALOG, PAS) 
{error  number  to  display) 
(our  internal  error  code) 
(error  message) 
{error  number) 


begin 

diafcErrHum  ToolErrorNuni.; 
QieckDiskError        (diskErrNum  <>  0); 

ourErrStr  'XXXX'; 
ourWhereStr  :  -  "XX*; 
If  dlakErrNum  <>  0  tJien 

Int2H«  (diakErrNuiT!,StringPtr( 

Longlfit  (^ourErrStr)+a)  ,  4)  f 
IntZH«£  (Where, St ringPtr( 

IjonglntOoutWhereStrj+l)  ,2)  ; 
OUrString        coneat   ('Disk  Error  $' r 

ourErrStE, 
'  OECurced  at  S ' 
ourWhereStr, 

4     I  \  ■ 

MakeATemplate   (SourAlert ,  aourSt ting) ; 
InitCursof; 

iteniClicked  :=StopAlart  (SourAlert,  Nil.) ; 


end; 


and,- 


(Save  the  global  error  nuniber) 
(Assign  function  result: 
-  TRUE  if  error  nonzero) 
{duimTy  ctiars.  to  set  length  byte) 
{durtrny  ctiara.  to  aet  length  byte) 


{Get  J^II  string  of  error  no . ) 

(Get  ASCII  string  of  our  code  no.) 
(Build  our  error  measage...} 


{Build  a  template  for  the  alert) 
(restore  arrow  cursor) 
(Brinct  up  the  alert  and  take 
the  user's  input} 
(end  of  IF  error  nonzero) 
{End  of  CheckDiskErtor) 
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The  alert  box  put  up  by  CheckDiskError  is  shown  in  Figure  4-IZ 

Note  thatCheckDislcError  calls  MakeATeraplate  to  define 
features  (text  message  and  an  OK  button)  the  alert  box  will  have. 
MdkeATemplate  is  described  under  "Constructing  Dialog  Bo 
and  Alerts"  in  Chapter  4. 
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Appendix  D:  HodgePodga  Organization 


Appendix  E 


Hodgepodge  Source  Code: 
Assembly  Language 


KP.ASM  312 
INIT.ASM  315 
MENU.ASM  324 
EVENT.ASM  330 
WINDOW.ASM  337 
DIALOG. ASM  353 
FONT.ASM  361 
PRINT. ASM  367 
to. ASM  371 
GLOBALS.ASM  373 
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HP. ASM  (main  program) 


Hodoepodge:    An  axajncle  Apple  IIGS  Vmsktop  apui ^cation 

Written  in  6SB16  ^5ssmbler  by  the  Apple  I  ICS  Development  Team 

Copyright  (e)  1986-37  by  Apple  Computeir,  Inc. 
All  Hlyhta  Eteservcci 


*  This  progran  and  Its  derivacives  are  llcenseii  only  for  ♦ 

*  use  on  Appl^  coJt^suters.  * 

*  * 

*  fforka  based  on  this  program  Jtiust  contain  snd  * 

*  conspicuously  display  this  notice.  « 

*  * 

*  This  software  la  provided  for  your  evaluation  and  to  * 

*  assist  ypu  In  developlnsj  software  for  tho  Apple  IIGS  ♦ 

*  computer,  ♦ 

*  * 

*  fhis  Is  not  a  distribution  license.  Dlstrlbiitlen  ol  » 
'  this  and  ocher  Apple  software  requires  a  separate  • 

*  license.  Contact  the  Software  Llcenilrig  Department  of  • 
■  Apple  Computer,  Ine,  for  details.  • 

*  DISCLAIMER  OF  WAflRAJJIY  * 
* 

*  THE  SOFTOABE  IS  PROVIDED  '-AS  IS-'  WITHOUT  * 

*  HAHRANTY  OF  AMY  KIND,   EITHER  EXPRESS  OH  IHELlED,  • 

*  WITH  RESPECT  TO  ITS  MERCHAJJTABILIT^  OR  ITS  FITNESS  * 

*  FOR  PiNt  PAaTICUIAR  PURPOSE.     THE  ENTIRE  RISK  AS  TO  * 

*  TWE  QUALiry  ftND  PEEtTDRHANCE  OF  THE  SCFTWARE  IS  WITH  • 

*  YOtJ,  SHOCIUJ  THE  SOFTWAHE  PROVE  DEFECTIVE,  im  (AND  • 
»  NOT  APPLE  OR  AN  APPLE  AUrHORIZED  aEPRESENTATIVE)  • 

*  ASSUME  THE  EKTIRE  COST  OF  ALL  NECESSAflY  SERVICING,  • 

*  REPAIR  OR  CORRDCTICW.  t 

*  Apple  does  not  warrant  that  the  functions  ' 

*  contained  in  t)ie  Software  will  meet  your  requirements  " 

*  or  that  the  operation  of  the  Software  wtl2  be  • 

*  uninterfupted  or  error  Tree  or  that  defacta  In  the  • 

*  sore ware  will  be  corrected,  • 

*  SOME  STATES  DO  SOT  AlLoW  THE  EXCLUSION  * 

*  OF  IMPLIED  WARRANTIES,   SO  THE  ABOVE,  EXCLUSION  MA^  • 

*  NOT  APPLY  TO  YOU.     THIS  BARRANTY  GIVES  YOU  SPECIFIC 

*  LEGAL  BIGHTS  AND  YOU  KNY  ALSO  HAVE  OTHER  BIGHTS 

*  WHICH  VAflr  FRCH  STATE  tO  STATE.  . 


ASMeSiSlfi  Code  file  "HP. ASK"  —  Main  routine  and  COPY'S  for  other  flies  * 
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i  Version  1.0  —  AugusL  1987  * 

I  • 


fiBSMDH  cm 
KEEP  HP 
tCOPSf      HP. MACROS 


fUttn^^tt*-*^******  **************  H  fl*»«a«««««r**>**««a«*«*Wf*«A 


aoajelodae  START 


i 

)  QldMl  equates  used  thraufltcmt  the  program. 


Rue 


Set  the  data  ban):  to  code  banit  so  I  cair  use  absoluta 

phk 
plb 


Save  addreas  of  D  tor  use  Later 
Stj.  MyZP 


;  Load  InlE  eMer^thlna, 


js;  StartupTools 
pld 


pi  a 

bnE  AilDone 


iKj-de  to  uso  for  QD 

;NBCE5Earv  becdiise  BCartUpTocsls 
;uEe£  Pascal  calling  convention 
•leaving  Input  pa rams  on  stack 


J 

;  Inttlallae 


systerti  flags, 

stz  ustViType 
stt  Qiiltrlag 
sti  Hindex 
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Zero  the  print  record  handle. 

BtB  PrlntReGord 
stz  PrlntEiacord+Z 


T.ake  events  until  user  quit*. 

jsr  minEvant 


All  is  done,  let's  shut  down. 


anoci 

jel  ShutDownTools 

Puahlonq  PtlntHecgrd 
_D1 a po seHa nd 1 e 


,-  get  rid  of  print  record  handla 

?  If  Print  Record  hAS  jero  In  it 

f  dispose  handle  will  fail  h«t 

,■  we  don't  care. 


copy  7/E16. WINDOW 

copy  7/ El 6. DIALOG 

COPY  INIT.ASM 

COPY  EVENT. ASM 

copy  M£Kt).,A5,M 

copy  WINDOW. ASM 

CO?y  DIALOG. ASH 

COPY  FOMT.ASM 

copy  PRINT.  ASM 

copy  10. ASM 

COPY  SLDHALS.ASH 
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NIT.ASM  (Initialization) 


Hsdg«Podge:    An  enampLe  Apple  IIG5  [>eshtop  appllCLaclan 


Copyright   (c)   19BS-B7  by  Apple  Cnmputer,  Inc. 
ail  nights  Be served 


ft5M6Sai6  Code  file  "IKIT.AEK"  —  Toolbon  stactup/ahutdown  routines  • 


IH1T.A£M 

Contains  the  fol lowing  global  data 

t^lD  Variable  holding  userld  of  this  program 

llll«Hdcle  Viirlable  holding  mode  used  to  start 

QuickDraw 

[KlgPort  Variable  holding  pointer  to  original 

port  ttiat  QuickDraw  has  vJhen  EtaftEd  up. 

Contilns  the  tollowlng  private  data 

lfH«ndla  Holds  handla  to  in^ory  "Lhat  is  used 

as  dirEct  page  tnr  the  tools. 
JPPtr  painter  to  ahoue  cnedbry, 

contains  the  following  public  procedures. 

fun<rtlDn    StartuproolB     IHodeToUse  :  SCS  typel   :  Integar; 

^tarts  up  the  cools  Unitializing  guickdraw  with  the  apeclfied 
mcrfl^}  and  initial  lie?  the  global  variables  above. 

procedure  ShutdcwnToolB; 

ihuts  thinigs  down,  undDlnn  uhat  was  don^  above, 

Uee»  the  HountBootDislc  dialog  routine  to  have  the  user  put  the 
Byeten  disk  on  line. 

trees-  the  Che ckTooi Error  dialog  royclne  to  cause  a  system  death 
(Iwuncino  apple)  if  the  A  register  is  nohwro.    The  X  register  ia 
aaeuaed  to  contain  a  '(fhero"  value. 

Change  History 

Juha      19B7    Steven  £.  Gla3» 
August  19B7    Ben  Koning 

Hodlfied  to  use  the  C  calling  convention  so  that  can  be  used  by 
both  C  and  TMLEaseal,     (input  parameters  are  rot  removed  frora 
the  stack.) 
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IJlitDulmiy  START 


COPY  T/E J S. MEMORY 
ENE 

StarcuptTools 

Input:  HodeToUA^  —  30080  for  640  mde 
Output !      ErrorCode    —  Error  If  noniera 


(KOTE:  DIFFERENT  FROM  C  AND  FflSCfll  VEBSiaNS) 


C»lling  Sequence; 


P*'^  ;  space  for  output; 

PuHhWord  IMode  ;  Mode  to  ues  fox  QD 

jsl  StartupToola 

Pl"  f  reranve  Input  paramoter 

;  get  func  result 

bne  MustQulc 

This  Is  a  suhroutlre  to  load  and  startup  sl\  tha  toojs 
an  application  general needs.     This  routine  also  gets  the 
space  In  bank  lero  that  tho  tcola  use  for  direct  page.  The 
only  cine  an  error  cutJa  other  than  zero  is  returned  Is  vtien 
the  boot  disk  is  not  on  lln«  ard  the  user  asltB  to  cancel 
rather  than  to  put  It  on  line. 

Order  of  work: 

1)  Start 

Tool  locator,  Hemnry  Manager,  Mlsc  Tools 
OulckDraw,  Event  Manager 

2»  Whan  these  are  running,  the  "one  nwment  please"  string  Is 
displayed  and  LoadTools  Is  called. 

QuickDraw  and  tho  Event  Manager  are  started  up  first 
because  If  the  LoadToals  call  returns  a  VolNotFound  error 
we  naed  to  have  the  volume  mounted.    This  Is  done  with 
the  TlWountVolume  call  uhlch  requires  both  QuicltCraw  and 
tha  Event  Manager  to  be  active. 

3)     Next  I  start  up 

Window  Manager,  Control  Hanager, 

Menu  Hanager,  LineEdlt,  Dialog  Manager 

4}    After  these  are  initial  lied,  I  setup  and  draw  the 
menu  bar  and  display  a  message  to  the  user  tjefora  I 
InltlalUe  the  rest  (Standard  File,  Font  Manager, 
QulclcDratf  AuKillary  and  print  manager). 


start upTools  START 

using  InitData 

HndeToUsB  equ  S5 

BesultCade         equ  ?7 
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,  

( 

!  DIra«t  Pa^e  use.    The  lol lowing 
I  dascrlbs  ho«  the  direct  pagsa  ai-a 
i  Co  the  tosls  be law. 


DPFortulclsDriw 

aqu 

SOOO 

;  naeda 

J 

DPFotSventMgr 

equ 

sjoa 

;  needs 

1 

DPFoiCt  LHgr 

aqu 

$40D 

;  flEGda 

1 

CPforLlneidU 

equ 

S5D0 

;  needs 

1 

tFFCitHeri'jHgr 

equ 

S6E0 

;  needs 

1 

CJTflrScdfLle 

aqu 

$700 

1 

BProrFoniHgr 

equ 

;  needs 

1 

Brfoi-Eriat^r 

equ 

¥900 

;  needs 

equ 

SBOO 

Line  is  called  wtien  t 
Else  IS  eet  It 


Plt> 


Cofy^  the  Input  parameter  Into  the  globjil 
diti  area  and  Initialize  the  result,  code 
ASSUfflirig  all   Is  well. 

Ide  HoderDlJEB,a 
Sti  ThisMode 

Ida  to 

at a  ReBultCode,  s 


I  ,  

; 

f  stsft  mith  TlStartup 
J 

JTLStartup 


t  Tool  Locdtor 


i  

I  Initial  lie  the  BiemorY  manager, 
f 

FUB^Hard  ID 
_MMEtartup 
Idit  tl 

jsr  ChackToolError 
pi  a 

sta  MylD 


I  InltlaliiB  iniic  tools. 


Htstartup 

Idx 

jsr  CheckTool error 
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Flfs^.  get  some  ircmory  for  tht;  zero  page  we  needL 

p}ta  ;  spacfl  fsr  handle 

pha 

PushLon?  f Total DP 

Push.Wnrd  latcrBanlt+atljfPage+attrFljied+attrLochBd 

^ushLong  ID 

_NeiirHaridlB 

Idx  t3 

Jer  checKTool Error 


Take  tfte  resulting  handle  (stiLl  on  the  staclc) 
and  dereference  it,  putting  the  pointer  into 
ZPFtr. 


ftui  !  Sivo  current  D 

tsc  ;  turn  staest  into  direct  page 

ted 

Ida  [3]                               I  derof  the  pointer 

Bta  Z?Ptr                           ;  wo  knoM  that  high  void  is  0 

pid  ;  restore  direct  page 

pla  ;  put  handle  Ij^tn  storage 


sta  ZPHardle 
pi  a 

9ta  K^Handle+a 


Nets  that  width  on  startup  is  320  to  allow  doubilng  the 
screen  width  when  doing  best  printing. 


Ida  tBPt,r 
clc 

adc  IDFFgrauickDraH 
pha 

?ushMord  ThisMode 

PushWord  t32Q  ;         glie  of  scin  line  in  bytes 

PushMord  HylD 

jODStartup 

Idx  ti 

jsr  ChecltrnB-lErro-r 

PushLong  tO 
_aatPort. 

PullLonq  OrlgEort 

Idy  mo 
Ida  ThlfiMnde 
cnp  t$BCI 

Idy  i32a 
oluTkoda  a  nop 

sty  Ks.nK 

Ida  ZPPtr 
cit 

adc  (DBFojcEvontMgr 


318 


Appendix  E;  HodgePodge  Source  Code:  Assembly  Language 


PushVford  120 
FuehWDtd  to 

Sushworfi  #0 
PusliWord  (200 
FusWord  My  ID 
EKStartup 

;  quaue  elze 
;  X  clajnp  low 
;  X  cldKp  high 
;  y  eiajtifi  loiif 
;  y  cl^Tip  high 

H  Cat  up  a  string  teLllng  user  chat 

something  is 

FtistiHord  t2a 
_MoveTo 

_SEcaaefcColor- 

_SetForECDlof 

FushLong  tMicgiientStr 
_D.raHString 

ShETWCursnr 


1  I 

;  Hike  the  LoadTcsols  call 

r 

iMdhgalR  _GET_FILE_INFO  ParamBloqjc 

bed  OicTDLoad 

j*r  Mount  aoctDi  Etc 

bsg  Loadhgain 


9ta  EtesultCode,  s 


;Tzy  to  find;  the  directory 

; '/SYSTEM/TOOLS/ .    Olt?  Go  load. 

;£2Be^  display  psuBdo-dlalng 
;Qid  they  select  "OK"? 
;¥es,  ao  try  It  again. 

;£lse,  they  seleoted  "Cancel", 
;So  retucn  result  code 
;and  leave  this  routine. 


OkToLoad  PuahLong  tTQUlTsble 

_Load't'(jg'l  s 
bcc  loolsloadad 

Idx  <E 

Jsr  CJieCkToolErtor 


:Fush  address  ol  tool  table 
{Attempt  to  Ipaij  them  (should 
;(rarli).    If  okj  go  on. 

ilt  error  Imppened  anyway, 
;ve'll  jiUEt  die  here. 


>  The  tools  are  loaded  so  start  them  up. 
S 

TOolsLoadcd 


anop 
_(pnuxstsrtup 


;  OulckDraw  Auxiliary 


WaltCurscr 


;  With  QIMux  started  we  can  Bhow  th^ 
;  watch  cursor 


PushWord  HylD 
_WiftflStartup 


;  Vfindow  Manager 


Idjt  *7 
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jar  Chedtrnal Error 


_He  EreshDe  5  Itrop 

Ida  ZFPEr 
clc 

adc  *OPFotCtLMgr 
pha 

_CtlStartup 
Iflx  19 

Jsr  ChecJttoolError 

fushWofd  M/ID 
Ida  ZPEtr 
clc 

ade  (DPForLlreEdlt 
Pha 

_L£Startijp 
Idx  fs 

jsr  CheckToaJ.  Error 

PushWprd  MylD 
_D  i  a  1  og  St  a  ft  up 

Idit  tio 

jar  CheckTool Error 

EushHord  f^lD 
Ida  ^pptr 
cic 

sdc  tDPForMSnuMar 
_KenuStartup 
Idx  #11 

jar  chBckTool Error 
_DeBKSt*rtup 
jsr  ShswEleaseHalt 
Idx  112 

jsr  ChBckrooJErcEn 

PuehWord  My ID 
Ida  Ipptr 
cj  E 

adc  tDPForsidFllo 

_SFSt4rtiip 
Id*  H3 

>r  Ch«cJtrcH3i Error 
Pushlftsrd  •S8O00 

PushWord  My ID 
Ida  JpFtr 

clc 

adc  IDPPoifFontHgr 
_FMscartiip 


display  desktop 
;  Control  Manager 


I  Dlaloq  Manager 


Menu  Manager 


r  Desk  Manager 

;  hfEssags  for  UBer 

;  Standard  File 


;  display  fila  narnea  In  all  caps 
I  font  Manager 
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Idx  114 

jsT  Ch«c!cTool£rror 

PusHHard  MylD 
Ida  ZPFtr 
clc 

adc  (DPForPrlntMgr 
pha 

_PMStartup 
Idx  (15 

jsr  ChecliTool  Error 
jsr  KldePledaeVfdit 
InltCursor 


Print  MaTuger 


reset  cursor  to  arro"  earaor 


All  Is  dor.E.    He  muEt  clean  yp  the  stack  and  get  out 


KrasntStr 
KIXX 


pita 
rtl 


;  restore  dtir 
,-  all  done. 


str  'One  niomenL  please^.," 
dB  2 


dc  H'PathKame' 

da  2 
ds  4 
ds  2 
de  2 

ds  Z 
ds  2 

ds  4 

Btr   ' •/SySTEM/TOOLS' 


;Pr(jDOS/lfi  Parameter  block 

(■With  pathname  as  Input;  rest  of  the 

; fields  wLlL  be  set  as  output. 


•  ffubliclnitData 

•  TB«»e  are  ijlatijl  Variables  available  to  tne  main  program. 
lubllcInitDATA  DATA  -Globs I 


f  Jublle  Variables 


HytD  ENTKi 
ds  2 

TblsHode  ENTHT 
ds  2 

QrtflPort  ENTH¥ 
ds  4 
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I nit Data 
ZPKandle 
ZPPtr 
Tool Table 


EndTabl* 


PrlHDflrA 

d£  4 

ds  4 

a  nop 
a  nap 

dc  I '  [EfidTable- 
dc  i'l,SQlDl' 
da  i'2,$0l01' 
1'3,S0101' 

dc  1'5,$D100' 
dfl  L'6, 50100' 
dc  i'H,?DI03' 
dc  i'15,$[)l03' 
de  X'16,$ai03' 
dc  l-l»,soi{Kj' 
de  l'lS,S01og' 
dc  1,'20,?01DD' 
!■  21,  iOioc 
1'22,5D102- 
dc  i'23,Sai00' 
de  l'27,soiDi)> 
dc  l-iS,S01aO" 


■St  art  Table)  /4  ■ 
;  too 


loeatnr 

JtiLgc  tbpla 
qulcJtdraw 
desfc  manager 
event  rftanagar 
wlndQw  jsanager 
inenu  manager 
control  manager 
qulcicdraw  aun 
print  manager 
line  edit 
dialog  raanagur 
scrap  jrana(jer 
standard  file 
Font  jiHiiager 
List  nianager 


****** 


ShutDoi»nTool* 
Inputs:  Hone 
Outputs;  Bone 

Shuts  down  every  thing  started  i.p  in  InltTcola 

ShutDowiTools  STAJtT 

using  InltData 


_De9l!Shutclown 

_FKShuLDown 
_PMs hut down 
_Sr,Shuci}gwn 
_DJalQgShutcl!)wn 
_1ES hut down 
_ltemiShiJtDown 
_HlRdShiitDown 
_CtlShutdown 


_^EM5hutDoHn 

_QDAujcSliutdoHn 

_BDShutDoMn 


;  shut  this  first  so  that  other  tools 
;  are  still  around  (clssa  DA's) 


r  this  is  shut  dowi  after  window  m}sr 
;  because  window  mcjr  mafc:ea  contol 
;  manager  calls  at  shutdown  time. 


Appendix     HodgePodge  Source  Code:  Assembly  Language 


_MTS hut down 

EustiliMiig  ZF Handle  get  rl.d  of  handle  for  dlreix 

DlBposeHandle  ;  page 

EuahWord  My ID 
_HKSliutijonn 

_TLShut(ioHn 

rtl 

EHD 
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MENU. ASM  (menus) 


Hodg«Fodq&:    An  exanple  Apple  IISS  Desictcp  application 


Copyright  (cl  l?B6-fl7  by  Apple  Computer,  Inc. 
All  Rights  Ragervod 


ASM55B1S  Code  IHe  "MENU. ASM"  —  Menu  InltlallLatlon  and  dispatching. 


*  Menu  iLEiE  la'a  • 


AppleMenuID 

gaqu 

1 

FlleMenulD 

gequ 

2 

EdltHenuID 

g«qu 

3 

WlndoHSHenulD 

geqii 

4 

TonteMEnuID 

gequ 

5 

UndoID 

gequ 

250 

;  TJriese  nexc  S 

CutID 

gequ 

251 

;  required  for 

copylD 

gaqu 

2^2 

;  TasKMastEr. 

Fa*tttD 

gaqu 

2SZ 

ClearlD 

q«qu 

25* 

ClofeWID 

gequ 

255 

are  standard  and 


AbautID 

gequ 

25S 

Quit  ID 

gequ 

357 

OpenSfiD 

gequ 

259 

SavelD 

qe-qu 

259 

ChooselD 

gequ 

260 

setupll} 

gequ 

261 

Print  ID 

gequ 

261 

ShowFontlD 

gsqu 

263 

Mono  ID 

gequ 

26i 

end 

Thesa  are  our  own  responsibility 


* 

*  DcManu 
* 

*  called  utien  TaskKaster  tElls  me  that  a  menu  Item  has 

*  been  solocted. 
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START 

gslng  GlohalHATA 


Ida  TasStDATft 

cciip  !  2S9  Is  dumny  do  nsthlnq  -  Lqnore 

beq  Unhillte  ;  dc  nothing 

bfle  DDMItem  ;  300  and  up  are  4dde<J  wlndnws 

pec 

abc  ♦UndoID 
asl  a 
can 

jsr  (HanuTablef 


PustiMord  tFsUe  ;  draw  normal 

fushWoTd  TaskDATA+J  ;  MhLch  menu 

_HliltaK«nu 

rts 


HoiuTiUe 


a.Tiaip 

dc  1 

dc  L 

dc  1 

dc  1 

dc  1 

dc  1 

dc  1 

dc  1 

dc  i 

dc  i 

dc  1' 


dc 
dc 
dc 


Ignors' 

igiiote ' 
Ignore^ 
ignorB ' 
ignore ' 
dsCloaeltem ' 
doAhoucIteii) ' 

dc?OpeTiItem' 
dosaveiCem" 
doCiiooaerltem' 
doSetupItein" 
doPrl ntltem' 
dcOpenl  L.e}r' 
doSetMono ' 


Edit  ItelKiH 


anop 


sec 

Ebe  »300 

ar.Qp 


In  A  Is  wlndcH  nonber 


esl  a 
asl  a 
tax 

Ida  wlndovlistiX 
sta  WhichWindow 
Ida  ijlndowllst+I,  R 
9ta  whlchnlndow^-*! 
jBr  doulndaw 

Jnip  unhillte 


clines  4  CD  inde;;  window  list 


;  done  with  It 


MENU. ASM  (menus) 


325 


UpMenus  START 

"Sing  MenuDATA 


PushLung  tPontsffenu 

PusJ;Word  fa 
_I  nsfl  rtHen  u 

PuBhLong  (0 

PiishLonq  iWindcwsHanu 

PushWord  (d 
_InsartMBnu 

PushLong  to 
Pushiojig  (EdltWenu 

PushWord  10 
^InsErtMenu 

PushWorij  to 
_InsertMenu 

PushLong  to 
PushLonq  fAppl^iju 
_S(ewHenu 
fush14ard  to 
_Ir,aertMenij 


apace  tor  return 


I  epace  for  return 


spaea  for  roc  urn 


apace  for  retum 


space  for  return 


PushWord  n 


rinlsh  olf  getting  the  nenu  bar  r«(ly. 


_f  IJtMeDuBar 
pla 

PuahWord  *10' 
_3etMIltleStan: 

_DrawHanuEar 

rts 


.-Discard  menu  bar  height 

;Set  starting  position  of  menu 

.-Actually  draw  the  manu  bar 


END 


Append.  E:  „oag«P„,0,  S,x.„  Code:  As..^^  Longuoge 


*****  **#*****»**"****-«-***"********"*fr**********"***'****** 


JUdToMenuE 


His  thfl  fact  that  the  last  SftTTEriLE  returned  in  REPLY  record 

iJia  name  at  the  file  and  the  state  of  the  request,    sot  PrlntAwail. 


START 

using  GlobalDhTA 
Ida  fl 

ata  PrlntAvail 

pUBhlOnc)  10 

_FrontWindow 

pla 

ata  whlchulndour 
plx 

stx  Hhlchwlndow+Z 

PUSHLONG  ID 
eUEBLONG  whlchHlndow 
_GetHrefcon 

pla 

St  a  Tenptiandle 
plx 

Jsr  Deref 
sta  0 
stiC  2 

FushWcrd  Ulndox 
FushLong  (Iddgt 
PushWnrtJ  fZ 
FuBtiWctrd  ID 
IntZDec 


Ida 

iddqt 

ora 

sta 

iddgt 

Idy 

tChLength 

Ida 

[01, y 

■nd 

clc 

adc 

ts 

tay 

ld« 

(0 

Jda 

sta 

(01,/ 

in^ 

tny 

inn 

Inx 

cpH 

hne 

cpyidlp 

Ida 

0 

clc 

adc 

14 

tax 

Ida 

2 

3dc 

fQ 

phi 

;Set  PrlntAvail  fliq  to  a!l<]H  pclntirg 
;it'£  the  front  window  we're  adding  in 

;get  result  for  pu^tiiftg  In  a  see, 
,*  space  far  result 
;refcoii  has  handle  to  data 


dfl  reference 


;  font 'a  e1z« 
,-ptr  to  string 
flergth  of  string 
(-unsigned  integer 

; convert  size  Into  an  ASCII  string 


,-get  rsmsB  lenijth 

;Ilnd  end  of  string  to  slide  stuff 


;  y  indaii  off  Ids  Is  HherG  vg  store 
;  X  index  off  Idn  Is  where  we  load 


;  do  fi  bytes 

;no«  pt.  to  Itailiat  loc.  for  insert 


MENU.ASM  (menus) 
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PUSHWORD  ♦$FFFF 
PaSHWORD  tWlndowsMfimilD 
_InsertMItem 

;  if  first  time,  omit  dumny  t99 

;  299  Is  duramy  Item  to  delate 
;  it '6  gune,  non  add  nex;:  on^ 

Pushwotd  t$£CtC 
PuBhKoxid  tWihdowsftenuID 
_SetMenuFlag 


ida  wLndflx 
tone  NoiFlrseTLme 
PushWard  t299 
DelEt^IcaM 


KotFiratTlme 


Ida  iTrua 

sta  NeedToUpdate 

Idd  to 

pha 
pha 

fuahword  tHindowsMBnuiD 

Ida  Hindex 
asl  a 

tax 

Ida  whichwtndcw 
3ta  WindowListjit 
tay 

Ida  whichvfindow+Z 
eta  Wliidc™Lls^+2,)t 

inc  vflndfljc 

Ida  tuflip-handle 
Idx  teniphandle+z 


re-calc  siie 

;  save  off  windou  Pointer  lar  raeru  etufr 
for  WINDOWUST  Irdeii 

;  bufnp  counter  for  fient  add  on 
;  olc,   let  this  loose  again 


IdA 

Iddgt 

idcr 

iddmy 


de  c*QO' 
il'13' 
il  "Q  ■ 


dc 

dc 


trill  sJlda  in  behind  It 

0D-J15  slides  Into  nil 

and  finaJly  a  carriage  return 

3  dLLUny  so  we  slide  exactly  a 
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Appendix  E:  HodgePodge  Source  Code:  Assembfy  Language 


*  Henij  Data 


DATft 


ieturn 


equ  13 


JppleWenu  dc  c'»9\XH' ,  I  'UppleMenuID' .IX'RETURN' 

dc  c'— About  HotlgflPo[lgc...\H',  l'Ab3utID',ll'B£TURfr' 
dc  C— \N50tJDSO' ,  il 'RETORU' 
dc  c ■ . ■ 

EditMeau  dc  Edlc     \DH ■ ,  i  ' EdltH^nulD' ,  J l '  REiniW 

dc  c-==U,ndD\*ijH' ,  1 '  UndoTD  M 1  ■  RETURN' 

dc  c'  \N500D\0',ll'RErURJ!' 

dc  c'—CutV^XxH',  1  ■CQtlD',  il- RETUHJI' 
dc  c ' — Copy\ "CcH ■ , i ' Copy ID ■ , 1 1 ■ RETUHH ' 
dc  C-— PasteS'VvH'  ,i  I  PasteJD' ,  il  'BETURM' 
dc  c-~CJear\K',l'ClearID',ll'IlETUftK' 
dti  q '  . ' 


FlieHanu 


dc  c'»    File  \H',l'FlleMeTiuID-,il-REHJHll- 
dc  c'—Open. .  A'OoH',  i'OpenWlD' ,  il  'lETURN' 
de  c— -cjQse\DHM  'CloseWIiJ',  il  'RETUflN' 
dc  C  —Save  As .  . .  \DH ' ,  1. '  SavelD ' ,  1.1  ■  RETURN  ' 
dc  c'  \N5Ci[JD\0Ml 'RETURK' 

dc  c-~chooaa  Prlntef ,  ^HM'Choo-selD" ,  1.1-flETUEH* 
dc  c---PagE  Setup.  ..\DHM' SeCupIQ',  11' RETyjW 
dc  o'—Print..  .\D"Pp^^',l'Prl^tID',ll'[^E^U!!H■ 
dc  C— \NSCiOD\&' ,  11  iRETUajJ' 
dc  C  — Oult\ "QciH' ,  1  'QultlD ' ,  U  '  RETURN ' 
dc  c ■ . ' 

dc  c">?  window  \DH' ,  1 'WlndoH^enuID- ,  11 'RETUHM' 
ENTRY 

dc  c' '-No  Windows  aLlQcated\N2S9' , 1 1 ' RErURN' 


FontiHenu 


HoanPropItem 


Monastr 
PtopStr 


dec's*     Fonts    \H' ,  1 'FantsMEnuID',  11' RETUftrl' 

dc  c""Display  FDnt.,.\*FfH',i'ShowFontID',lI>RErURB' 

EHTEY 

dc  c— ulsplay  Font  as  Mono-spacedV'UnH 1 'MonoID' ,  11 ' RETURN ' 
dc  c'.' 

dc  c"— Display  Font  as  Mono-spacBdNH ',  1 'HonolD' ,  il 'RETURN' 

dc  c'--Dlsplay  Font  aa  P report lonal\ •MtnM ',  i'MonoID' ,11 'RE TURN ' 


••""NOTE:  300  is  starting  nuraJier  for  a  building  list  -  ^ss'i  in  AddToMenu 
***'■'  299  is  tfiE  d^tnnvy  one  that  is  deleted  when  we  gee  a  real  one 


EHD 


MENU.ASM  (menus) 
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EVENT.ASM  (mafn  event  loop) 


fif^dgePodget    An  e««»ple  Apple  IIGS  D«mop  application 

Copyright  (c)  lSB6-a7  by  flppie  Cen^puter,  Irt. 
All  Rights  flfiaerved 


*      ASMesaie  code  file  ■EVENT. ASM"  —  TasitMa 


star  cill;  DlspitehlTig  tn  all 
other  routines,-  ?tenu  diiwlng. 


Event 

This  contains  the  main  event  loop. 

 *"•*•* 

MslnEvant  START 


Again 


AllDone 
TasklablE 


•nop 

Ida  QaitFlag 
bne  All Done 

jsr  ChflOcFrontW 

PushMord  tQ 
PushWord  tSFFFF 
PushLofig  lEventHecord 
_Tas)(Masta(- 

pla 

ti«q  Again 

asl  a 
tax 

jsr  (5asf!TablB,j(i 

bra  Agatn 

rts 


Ewent  tnanager  events 


dc  1 ' ignore ' 
tic  i'lgnnre' 
do  i  > Ignor* • 
dc  1' Ignore' 


JHas  Quit  been  salett? 

if  EC,  Stop  the  loop. 

; Handle  the  menu  dlsyenable 


;Ha  event?  loop. 

/Multiply  by  two, , . 

,-ase  for  index  lrjto„. 

fdispatcti  table  to  execute  evejita 


;  0  null 

;  1  BKJUae  down 

t    2   IDOUAQ  Up 

;  3  key  down 
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1 ■ Ignore ' 

4  undefined 

<3c 

i ' Ignore ■ 

S  auto-key  down 

dc 

i '  lijnpra ' 

&  updatE  event 

dc 

i '  ignoife  ■ 

1  undefined 

dc 

i 'Oqflctlvate ' 

e  activate 

dc 

^  switch 

dc 

!■ Ignorft' 

■  10  defik  acc 

dc 

i" Ignore" 

■  11  device  driirer 

do 

i' ignore" 

•  12  ap 

dc 

1' Ignore' 

•  13  ip 

dc 

1. "  Ignore ' 

f  H  ap 

de 

1  *  igr.orfl ' 

■  15  ap 

t 

;  Tul<  [Baiiter  events 


dc 

i' Ignore"  ; 

0  In  desic 

dc 

i'l^eHanu'  ; 

1  In  HenuBar 

de 

i ' Ignore "  ! 

1  in  systeir  window 

dc 

I '  IgJitlJrfl  "  , 

3  In  content  cif  wlndui 

de 

i'lgncxe'  , 

4  in  drag 

dc 

1" Ignore'  , 

5  in  grow 

de 

1 'Decloseltem' 

6  In  goaway  —  ajune  as  "•close"  item 

dc 

1' Ignore' 

7  in  iDoEft 

dc 

1'  Igtwfe' 

e  In  info  bar 

dc 

1 '  DcMenu ■ 

9  in  special,  menu  item 

de 

I 'Ignore" 

It}  In  opentiCA 

(JO 

1' Ignore' 

■  11  In  frame 

dc 

1' Ignore" 

■  In  drop 

END 


»  OsecicFtnntW 
■ 

*  Checks  to  see  It  front  window  bi.a  charged  and  if 
I  AO  deals  uitti  Various  menu  enables  «nd  disables. 

•  ulled  by  main  event  loop,  and  activate  events. 


CbackTrontH  start 

u£ing  MenuCata 
using  GIobalData 

pushLong  10 
_FrontWlndow 
fullLong  ThlsHlndoH 

Ida  ThisWlndow 

cinp  LastWlndoH 

b-ne  clianged 

Ida  ThisWindcw-^^ 

aap  I.astWindoH^2 

bne  Changed 


Eilltl 
Changed 


Ida  IhlsWlndow 
ata  Laatwindow 
Ida  Thi^Wlndow+i 
sta  Laatwlndow+2 

Jsr  TypeTfiisW 

Ida  ThlsHType 


;gert  th«  current  front  window. 

; Check  ts  see  If  it  is 
I'still  tt]B  saMe  window  as 
.-last  time 


;Ho  Change  Ho  problem. .. .Else, 
fLastWlndow  ThlsWlndow 

SSet  ThlaWType-type  of  Che  new  front  win 
;arrivijig  here,  the  window  has  changed^ 


EVENT.ASM  (mafn  ev©r\t  loop) 
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beq  EKltl 
]ok  so  start  changing  menus 


;lfe  type  may  not  have  cliangod. 
;B.rancti  talcen  If  the  Jitter  1b  true. 


TherelBl 


cmp  ID 

bne  there l£l 

jsr  SetupForNoM 
bfa  flnlstitJp 


CtDp   f  1 

Isr  SetHpForDaW 
bra  FlnlshUp 

]ar  SetOpFor^^jptf 


1  And  drop  Into  flxlt  stuff 


rlnUhUp 


EteallyDanE 


Lfla  ^!e6dToUpclate 

_DrawMeniiBir 
stx  NeedToUptiate 

Ida  ThleWTyiw 
at a  LastHType 


; Is  there  a  front  windou 
,'tske  this  branch  If  thare  Is, 

;it  no  front  window  than  dieable 
;vAtinii3  thing  I  care  about  and  go 
; Finish  up 


,-ls  it  a  aystein  (Da) 
;taJtan  if  not. 

I'elsB  it  la  a  da.  da  what's  needed 
;and  do  the  exit  etiift 

;A-rsg  -  Wtype.  Go  deal  w/irenu  stuff 


;haE  the  snenu  bar  changed 
;cal!en  if  not.  else 

;we  need  to  re-draw  the  tnenu 
;and  say  we  did  it . 


;LastWType  :-  ThlsHTypa 


•  figure  out  the  type  of  the  front  window. 

*  D-  thera  is  no  window,  1  -  It's  a  da  vjindaw.  2  -  flpp  Font  Win.  3-  App  Pic  Win. 
TypaThisH 


OaneEarly 
ttasApp 


a  nop 
Ida  ThlsWlndow 
era  ThlsWlndow»-2 
sta  ThlsWTypE 
beq  DoneEarly 

PuEhtford  IQ 
PufihLnnfl  ThiEWlndoH 
GetSysWFlag 

beq  HaaApp 

Ida  tl 

ata  Thistriype 
rts 

Anop 

PusriLong  ID 
PushLong  ThlaWlndon 

_GfltWrefCon 

pla 

St  a  Tfln^ 
plE 

SIX  Tfflapt2 
jsr  deref 
Eta  a 

StK  7 


jwaa  thera  a  wlndcmt  at  all  7 

,-lf  no  front  window  then  ThlaWtype-O 
.-tdken  if  there  really  was  no  front  win 

;get  and  save  wuther  or  not 
fthls  is  a 

;Eyst«n  windBw  nr  not. 

Riearis  not  a  sya  window 

;lt's  a  sys  (da}  window  ^o 
;sBt  lastwtypa  -  1 


;lt's  an  app  win,  find  out  what  kind. 

I'^pace  for  get  ref  con  In  a  sec 
I'else  I  have  tlie  window  ptr 

,'get  refcon  It  haa  handle  to  data 

,'reeon  handle  to 
ftenp  and  A/X 


;iocJ(  It  down  for  a  sec 
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imp 


(oFlag 

Ida 

beq 

PlcW 

Ids 

t2 

Eta 

ThlsMType 

bra 

Ida 

13 

Bta 

ThlaWType 

Ida 

Temp 

Idx 

Temp+2 

jsr 

rts 

ds  A 

fCheok  If  plctura 
;get  wlnetcw  type 


;it*s  a  font  windaw  so. 
;sa.y  so  and 
; split 

;lt'fi  a  pic  windont.  so 
;say  an  and  split. 


funlcic):  the  refcon  handls. 


mstflr.dov  ds  4 
lastKindou         ds  4 

•  doQuttltem 

•  Scti  quit  fla?. 


(loQultleen!  START 

uslfig  GldbalDAtA 

Ida  ITrue 

sta  QuitFlag 

Its 

m*mttt*t*irit±*t»iriit*u*AA*irirmmM***t  If  ti***iiir*p  If**  ************* 

*  DoAcClvate 

4 

<  Handles  activation  of  windows  and  adjusts  the  edit  m^tin 

'  based  on  window  type. 

* 

tt*tnii**m*vait*»ttik*li*1imvlittmmmt1i*imiitt*1r1r  ************************ 

DahceivaC.^  SC.att 

ualng  GlobalData 

Ida  EventModlflars 
and  f] 

beq  end  ; don't  csre  about  d&actlvate  3 

Jsr  CheclcFrontW 
«iid  rts 
END 


EVE  NT.  ASM  {main  ©vent  loop) 
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•  SetUpForAppM 

•  seta  tha  edit  itionu  Items  up  ior  cha  application  windows 

•  that  is  al cabling  then.  And  sets  the  other  fils  menu  items 

•  accordingly, 


NoSaireEnaiila 

Cont 


SetUpForAppH  Start 

Ufitjifl  GlobalData 
Using  M&nuData 

EushLsng  10 
EushWoFd  f Save ID 


Ida  ThisMType 
crap  f  3 

bne  NoSaveEnable 

PushWord  (True 
bra  Cent 

PushWord  t False 

PuehWord  *c1d9«HId 
PUshHerd  fTrua 

Ida  PrlntAvall 
beq  SAlpPrint 

PushMord  lETintre 
Pushword  ITrua 
PushWord  fSetUpID 
PUBhWord  (True 
Jsr  ChangsMlteras 

Ida  LaatHType 
cmp  ft 
bna  Elxit 

Pu«hHoTd  t$0Q80 

PushWord  #i:aitMenulD 

_SetHenuFlag 

Ids  ITrue 

Bta  NeedToUpd^te 


SkipPrlnt 


Exit 


AS 

END 


.■get  ready  id  call  changeMitema 
;Me  gonna  do  save  lt«ii,  but  we  need 

.-to  figure  out  whether  It  should  be 
.-enabled  or  not.  Is  ie  a  font  wlndnw  ? 
fir  so  dont  enable  the  save  item. 


;elsa  push  trua  toi  enable 


;Has  it  a  da  last  7 

,*it  not  WE  don't  need  to  da  vihats  next 
.'disable  edit  Jtienu 


,-set  update  flag  so  i  only  redtaw 
;the  menu  bar  anoe 


•  setUpFoeNoW 
* 

•  Sets  the  edit  menu  Items  up  for  the  desk  acc  window! 

•  that  is  enabllnj  adit  menu,  and  close  In  file  menu 
»  accordingly. 


****  tV*  Hr**m 

SetUpFprNoW 


Uaini)  GlobalData 
tiaing  KenuData 


Puehlting  10 
PushWord  tSaveli) 
PuahWoid  #Falso 


,'end  of  list  mart  first. 

,-disble  save 

,'  1  desire  disable. 
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PushHcfd 

PushWord  #SfltLfpin 
FushMord  t Fa lee 

PUihword  IFalse 
jsr  ChangeHItems 

Ida  LastWType 
cap  II 
bne  Exit 

FushWard  I  SODS  CI 

SushWord  tEdltMBniilt) 

_£istMenaFlag 

Ida  ttrue 

3Ea  NeedToUpdiite 


)uh3t  was  it  last 
;was  Lt  a  da  Ust  7 

;lf  not  VIE  don't  need  to  do  whata  next 
f disable  edit  menu 

jset  update  flag  so  T  only  redraw 
;tha  menu  taaf  onco 


Dtlt  fta 
End 


'  SacUpforOaW 
* 

'  Sflta  the  edit  menu  Items  up  for  the  desk  acc  window; 

'  chat  Is  enabling  edit  menu,  and  cLaee  in  file  utanu, 

■  accordingly. 


SetUpForDaM  START 

Dsing  QlobkalData 
Using  MenyDaca 

Fuetil^ng  IQ 
juanword  tSavelD 
PushWord  fFilse 
PushHdfd  < Print ID 
PushHard  tFalse 
PusWpfd  tsatUpID 
PUEhWord  (Falsa 


;end  nf  list  mar*  first. 
,-dlsbl«  save 
;i  deslra  disable. 


PushWord  ICioaeMlD 
PuBhWoed  IT rue 
]sr  ChangeMItems 

Ida  LastHType 
cnp  11 

beq  £xit 

PushMpjrd  t^ffTf 

PushHord  lEdltManuID 

^SetKenuriag 

Ida  ITrue 

ata  (TeedToUpdata 


f anable 


;ifhat  was  It  Ust 

;vas  It  a  da  window  last  ? 

fit  HO  Hfl  don't  need  to  do  fhste  nast 


variable  edit  raanu 


;set  update  flag  so  I  only  redraw 
;the  manu  bat  onca 


Exit 


Esa 


EVENT.ASM  (main  event  loop) 
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■  Enab Its /Disables  th«  varlQus  menu  It 

■  flags  puLEhed  on  sta<:li, 

*  Entry  Stack  UiakB  ItJte: 

*  a 

*  ItefliiD 
* 

*  IteralD 

*  Enablfl/DiBable  FUg 

*  Return 


ChanijeMItamE  Start 

FullMord  ReaTemp 

Ida  3, a 
beq  Dona 


bne  OoEnabla 
bra  LP 

_EnabI.eHItejii 
bra  Lp 

f ullLonq 

fuahWord  ReaTemp 


IKiEnabla 


RtaTamp 
EnableFla? 


mma  acco^dlnq  to  tha 


;lon^  Indicator  of  end  of  items 

;word  iteni  id 

; (word)  true  -  enabla 

;void  item  id 

;  (word)  true  -  anable 

.■word 


;sawe  return 

; check  for  end  cf  llaK  marlc 
flf  so  split 


if  ve  should  enable  itams 

.-else  disable  them 
isn-d  start  aver 

; enable  Iten 
•iQnv  more  time 

;pull  and  of  Hat:  marlc 

;push  return  addrasa 


da  2 
da  I 
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WINDOW.ASM  (windows) 


I 

'  Kodgcff  odge:    An  exajnpla  Apple  IIGS  Oefkitop  af^sllcatlon 


copyright  (c)  1986-87       Apple  computer,  Inc. 
All  nights  Reserved 


ASMS 58 16  Code  rile  -WIWDCH.fiSM"  —  Open /Close  windcwa 


♦ 

'  HldeAll Windows 


JUdiMlWindows  STMT 

using  GlobalDATA 

sti  VIndes  .'Index  for  list  of  what  wbb  wis. 

RldsLoop  PushLong  ID  ;hltje  'em  all,  looks  fieater 

^Frontnindow 
Idx  vindex 
pi  a 

St  a  VTsble,* 
pla 

sta  VTabU+2,  x 
cmp  *a 

Ida  Vtable,K 

tane  dohld 

rts  jalJ  vis.  windows  hidden  now 


doKld  pha 

Ida  Vtable,  x 
pha 

_HldeMliidow 
Lda  Vlndex 
clc 

aac  t4 
sta  Vindex 

bra  Hldeloop 

END 
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DoOpenltflm  ; 

1)  MakB  sura  not  tco  maciy  windows  open  already  —  niay  show  dialog 

2)  Call  AdaToMenu  ta  add  Its  name  into  the  "windows"  menu  list 


DoCpenltam  START 

using  GlobaiDATA 
using  Font DATA 

Ida  Hinijex 
cmp  tLastWind 
bcc  DJcToDpen 
jsr  ManywJndDlalog 
sec 
rtfl 


DdttB 

□IcToopen 


i9.r  H^nKlndow 

bcfi  Dgne 

jmp  AddToMenu 


f Check  if  ton  nany  windows  open  already 
otherwise  "windDw"  menu  overflows! 
,"No,  sa  go  ahead  srd  try  to  open  one 
fYEs,  so  confront  us«r  with  dialog  box 
;SEt  carry  because  It  didn't  happen 


jlf  wa  didn't  open,  qlon't  add  it 
;Add  it  to  the  menu  list  and  eult 


END 


•  Do^avtltem  : 


DoSav«ItGin  STflHT 

UHlng  GlobalDKTA 
UHing  lOData 


puahlong  to 
_FrontWlndow 

pla 

at a  whlcnwlndotf 
plK 

stx  whlchwlndaw+2 

PUEHIONG  10 
PUSHLOKG  Hhlchwlndou 
GctWrofCofi 


pla 

plx 

jar 

derot 

St  a 

0 

St  a 

ftefptr 

stx 

2 

stx 

Refptr+2 

Idy 

♦oFlag 

Ida 

beq 

olctosav 

Its 

Jit's  the  front  window  we're  saving 

;get  result  for  pushing  In  a  sec. 
; space  for  result 
frefcnn  has  handle  to  data 


! check  If  picture 

?aave  only  type  0  windows 
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Emltoff 


CatWTitlB 

sta  HamePtr 
plx 

fit*  iiaiii«ptr+2 

PushWord  t20 
PuehNord  tld 
Puahliong  tErompt^ 
PusiilciTig  NacnePtr 

PiiBhLong  I  reply 
_SFPutFll.e 

Ida  r_good 


anop 

JfaltCuraor 

Ida  Refptr 
■ta  D 

Ida  Refptr+2 
sta  2 

Idy  #i}Handle 
Ida  10], y 
sta  Flctlandls 
Iny 
iny 

Ida  [01, y 

eta  ?icKandLe+2 

Ida  FicFSandla 
Id*  PlcHsndle+Z 
jar  DeR«f 

sti  ElcDestOUT 
stu  PicDestODT*! 

Ida  »R_fullPN 

Ida  l"R_FvillPN 
sta  NoiiwPtr+Z 


(■space  Tor  result 


!  y  loo 

;  prompt  string  pointer 

;  Fils  name 

,-  Max  file  name  length 

,'  Eoply  list  result 


;  o  0  means  OK  to  load,  it 


this  de-refd.  Is  the  data  tn  write  oute  picjiar.dle   (we'll  de-allDCate) 


}  rte>w  point thg  tn  what  we  write 

;  put  pointer  to  najne  in  l/o  para.*!  block 


Jsr  SavfiOne 


flxTmi 


Ida  tefptr 
cLc 

adc  loLen^h 

sta  S 

sta  refptr 
Ida  re£ptJC+2 
■dc  IQ 
£ta  2 

sta  refptr +2 


aoM  fix  up  nama 

where  the  name  will  qa 

saw  In  f}f2  also  fi^r  later  Indirect 


Ida  £  FnaJDe 
and  I^OOFr 
tay 
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cpytini 


long a  off 
Ida  r__Fnajnfl,y 
sta  I0\,y 
dey 

rap  ttOOlOOOOO 
longa  on 

pushlong  refptr 

SBtMTitls 


f  (It  points  to  strlD!)  now,  reraernbar? ) 


Ida  10 

pha 

pha 

Pushward  iWlndouEMenuId 
CalcHanuSlie 


ca-calc  size 


QuttaKere 


Ida  plcHandle 
IdK  PicHandle+2 
jsr  Unloelt 


InltCursor 


retptr 


rts 

ds 

EM) 


*  OpenWtndou: 

1(  Call  SFSETFILE  to  jet  name  of  file  to  display  In  window 
(or  th»  dlilog  x.a  select  font  U  Displav  Font  call) 

i)  Gets  iriEmDry  fof,  and  loads  the  picture^font  data  Into  memory 

3)  Alloeatei  a  new  window 

a)  puts  handle  to  MyHlndowlnfo  Ir  MrefCon 

b)  note  that  routine  to  draw  picture  contents  Is  set  to  "PMST" 
e)  not*  for  font  draw  contents  U  "DISPFQNTHIND0«" 

ThB  definition  of  HyWindowlnfo  is  contained  in  global  data 

If  the  menu  manager  is  being  used  to  add  Itenllsc  Items  with  the  file 
name.  It  will  squeeze  the  \M  etc.  together  (see  AddToMenut .    In  any 
Case,    the  file  najns  string  lot  the  windcsW  title  can  Still  be  found 
starting  at  this  areatS 

returns:     carry  set  -  didn't  open  It   (user  cancelled  SFGETFIlt} 
carrv  clear  -  window  opened 


OperjMlncSow 


START 

uslnc;  GlobalDATA 
using  iDData 
using  Font  DATA 
using  HlndciwData 


Ida  TasitData 

cmp  tShowFontlD 

hne  AsliUser 

jsr  DaChooseFnnt 

bcs  3tp 

jnp  DoTheGpen 

rts 


Is  it  opsn  for  font  window? 


; can ceiled  choose  font 


340 


Appendix  E:  Hodge  Podge  Source  Code:  Assembly  Language 


*  call  SFGETFILE  to  sequeat  the  file  name 


******** 


lUadleErraE 


Ida  HO 
pha 

Ida  120 
pha 

PushLong  fPrcxnpt 
PushLong  iOpenFlltsr 

FLiehLong  ireply 

Ida  r_gQott 
bne  loadltup 

res 


to 


pronipt  sErtng  pointer 
Do  dlmnied  display  of  unloadstales 
list  of  typea  to  Include  —  fJ  for  all 
nply  list  reiult 

OQ  neans  OK  to  load  It 

carry  set  ratuxn:  didn't  open 


*  Cat  *Ekace  for  th«  picture  file 


******** 


load: t Up 


FU£hLong  fO 
Fu£hLong  199000 
PushHor<f  My  ID 
EushWord  ($0000 
FushLong  10 
N«uHandle 


;  space 

;  size 

f  W 

r  no  restrict lona 

;  iDC  not  Inportint 


DoTlieQper, 


pi* 

st«  ficHandle 
plx 

stx  PicHanclle+2 

bcs  HindlcError 

jgr  Deraf 

9ta  PlcDestlN 
stK  ?lct>astIN+Z 

mop 

PushLeng  fO 

PushWord  MylD 
pu^fiWotd  tSCOOD 
PushLong  10 
MewKandle 


;  if  BrxDC  Dccurad  frsn  no  hand la 

7  darefanca  handle  (in  a,  k} 

;  put  painter  In  l/o  paran  block 


,■  apace 

;  slie 

;  Id 

;  fixed  and  locked 

f  loc  not  important 


pla 

sta  rcfccn 
plx 

9tx  refccn+2 

bcs  HandleErroJT 

jsr  daraf 

Bta  refptr 
aia  0 

stx  r*fptr+3 
stx  2 


;de  ref.  toi  storing  atatt  into 
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*  start  by  assuining  this  ulll  bo  a  picture  window  (not  a  font  Hlridotf) , 

*  Wb  set  the  address  of  the  drawing  routlnfl  to  EAINT  and  set  the  flag 

*  In  MyHindDwlrfo  record  tn  0  indicating  picture. 


Ida  fPalnt  ;  first  the  address  of  tho  Paint 

Bta  DrawRtn  ,*  routine 

Ida  ♦-Paint 
sta 

Idy  toFlag  f  How  set  the  tlaq  field 

Ida  to 
sta  [Q|,y 


;  Now       See  if  that  slily  aaatmpili 

r 

Ida  TaskData 

cmp  tShnkfCnntlD 

bne  set  10 

Ida  tl 

ora  MonoFLag 

ata  [01, y 

Ida  besiredFont 

sta  PicHandle 

Ida  DesiredFont+I 

Bta  FicHandle+1 


m  above  was  coi-ifect, 

;  lQO<  at  the  menu  item  that 

;  brought  us  tiere, 

;  not  the  fant  one  ao  qo  on 

}  tlx  th«  flag  fltid 

;  s«t  bit  lit  monaspacBd  font 

;  {y  still  set) 

;  put  tha  chi>£en  font  id  where 

;  we  Hill  later  put  It  In 

;  the  MyWlndowInfo  record 


Ida  fDiapForvtWlndow  ;  firially,  flu  th»  pointer  to  the 

sta  Dcavatn  ;  drawing  roLtina 

Ida  fQlspFontMindow 
fita  OrawHtn+2 
jap  HdHovSan 


Set  10 


Ida  »R_fullPM 
sta  NamePtr 
Ida  (''K_FullPN 
sta  MajtiEFtrfZ 


put  pointer  t{>  rmma  in  l/o  patam  blodi 


load  ptctgre  In  "BamePtt"  into  'Piepest" 


ier  LoadOne 


lOError  anop 

PushLong  RefCon 
_Dlsp<j3eHaridle 
PushLong  PlcHandie 
JJlspose Handle 
sec 


load  it 


There  was  an  error  ioadinQ  tha  file 
so  dlapusfl  of  the  memory  that  we 
allocated  while  trying  to  create 
this  window 
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*  HDva  tha  f  ll«s  name  inco  the  paracn  bloclc 


Ida  reCptr 

sea  Q 

Ida  re£ptr+2 
sta  2 

Ida  pichandle 
Idy  loHandla 

sta  [0],¥ 

Iny 

Idd  plcliandle+2 
Bta  [ai,y 


Idy 

Ida 

Eta 

[01,1' 

Ida 

raf ptr 

elc 

ad.c 

sta 

windaddr 

sta 

0 

Ida 

refptr+2 

adc 

«{! 

sta 

Mlndaddr+2 

Bta 

2 

Ida 

and 

cmp 

bnl 

KajneLenOK 

Ida 

f  MajcHaEieS  1  ze 

Sep 

» too 100000 

sta 

r  Fname 

rep 

IIOOIDOOOO 

tay 

Sep 

tioaioO'Qcia 

Longa  off 

Ida 

r  Fnaiiie,y 

[01,  y 

dey 

tp-1 

cpynm 

ttQQlOOOOO 

longa  on 

Idy 

13^0 

Idx 

atx 

DataWidth 

3tX 

mew 

aty 

;xig,e  lero  page  for  Indirect  stores 


!lnto  the  recfun  area  (refptrj 


;  Put  blank  in  record  at  blank  riald 

;  (nota  this  16  bit  store  will  av&r- 

t  write  the  length  field  but  we  don't 

;  care  since  we  fix  It  below. 


where  ttie  nanie  will  tja 

save  In  0,2  ales  lor  later  Indirect 


; adjust  max  sis 

; adjust  pixel  count 


;  %VL  up  the  DiataKelght  tuEsd  on  the  type  of  window  it  Is, 

t 

I Ida  tliB  ;  assimte  picture  and  make  ?00  the  ndX 

sta  D^taKelqht  ;  tlelgtit 

Ida  RefPtr  ;  now  see  w!iat  it  really  Is 

sta  0 
Ida  RerPtf+J 
Sta  2 
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KotlsPicture 


Ida  TasJcDaca 
bna  MOtlsPlcture 

PushLong  OrigPort 
Set  Port 


GetFontiD 


;  Oae  tho  original,  port  obtained  durlfig 

;  startup  to  milce  sure  ^  port  Is  sat 

;  for  th«  foiloHlng  text  s1!e  calcs 

;  save  this  on  the  stack 


Idy  loFoneiD+-2 

Ida  .[OJ,y 

pha 

dey 

dey 

10], y 

pha 

PashWord  10 
_lnatallFont 

Pushlfng  iriRacord 
_G«tlF'oEitlnfo 

PUshlong  ID 
Ida  aeceni; 

ClE 

pdc  Descent 
pha 

PuahWord  fMumLlnes+2 

Jlultlpljf 

pli 

sta  Data Height 
pla 

Jsr  rindHaxWldth 


f  now  Install  Che  font  that  will 
;  be  used  In  the  currant  port 


;  get  the  font  Info  so  can  get 

.  accent  and  descent, 

;  space  for  result 

;  nav  multiply  sum  of  aaeent  (. 

,■  descent  by  num  lines  to  draw 


;  put  result  In  DataHeJ^ijht 

;  itrlp  off  high  word  of  nothing 


PuahWord  »0  using  aaved  font  Id  on  ataoH 

_lJi9tallFont  ;  ra-lnstall  tBe  orig  font 

laPlcture  anop 

# 

*    offset  vpparleft  corner  for  opening  of  window 
Idit  to 

MovOff  Ida  IsUPchSjH 

clc 

adc  MyoffBst 
sta  £lzPos,x 
Ida  r£iiPoa+2,ji 
cl  c 

adc  Wxoffset 
Bta  Sl!Pos+Z,)t 
inx 
iax 

tax 

cps  #8 

bne  MovOff 


Ida  WitOffsat  ; adjust  offsets 

clc 

adc  #20 

sta  WxOffset 
Ida  HyOffset 
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clc 

cmp  *120  rlf  we  get  too  low,  start  at  top 

bne  DoYset 

Ida  flZ 

ik><fiet  St  a  Hy  Off  sat 


PushLonq  (0  f  Space  for  result 

pushlong  IMintloviPataiiBlocS: 
[ieuHlndau 


"  Mow,  FlnaHv,  create  the  new  window 


pla 

fita  whlchmindou 
pla 

St  a  whleh«inii<}w+i 

Ida  PlcBandle 
IdK  PicKanidle+2 
jsr  Ufilock. 


;  LTse  ttie  original  port  nbtained  during 
;  startup  to  make  sure  a  port  ia  set 

;  unlock  handle 


ft  Forca  origin  bourdarieH  (see  Manual  definition  of  utindow  Mgr'fi  SetOrlginMask) 


PUEhWord  fSFFFE 
?UBbLong  wtiichwlndo^w 
_SEtoriglnHasl( 

clc 

end 


;  carry  clear  return:  we  opened  It 


*  HindoMData 


I 


Hlndaddr 
r«f con 


Sac  alf  eight 
Datakiridth 


I 


data 

alt  anop 

dc 

12 

WindowEnd 

-w  I  ndowP  ar  anffl  1  ock  ■ 

dc 

tz 

FTitie+FClose+FBScroll+FBScrDll+FGroM+Floom+FTfciVe+FVia' 

dc 

14 

£)■ 

Ptr  t&  title 

dc 

14 

0' 

ttefCon 

dc 

1? 

Q,D,Cl.O' 

Full  Siie   (0-  dafault) 

dc 

14 

0' 

Color  Table  Pointer 

dc 

12 

o< 

Vertical  origin 

ii 

0' 

HnriSdJital  origin 

dc 

12 

Data  Area  Height 

dc 

12 

640" 

Data  Area  Width 

dc 

i2 

Max  Cant  Height 

dc 

12 

MaK  Cont  width 

dc 

12 

4" 

Nun^r  of  pixels  ta  scro-ll  vertically. 

dc 

IZ 

16' 

Number  nt  pixels  to  scroll  harisontally 

dc 

12 

40' 

Number  of  pljtelfi  to  page  verclcaily. 
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SlzFos 


ftefptr 


Ascent 
Descent 


dc  Ifl '0' 

<lc  Ifl 'Paint' 
■^c  i2'0, 0,(3,0' 
dc  i 4 ■ 5Ff FFFFf P ■ 
dc  U'D- 


anop 

Us  2 
ds  2 
ds  i 


I'^a. ID, 80,350' 


Info  bar  height 
SeJProc. 

Routine  tc  draw  i^fo.  bar. 

ftoutlna  to  draw  content 

sjze/pos  of  cent ant 

Plane  to  put  window  up  in 

Addre..  f„r  .in,,«  ^^^^^^^^^ 

f*i"'=^^  tc  bytos 
.siiE/pos  pf  content 


END 


OpenFilter 
On  ^ntry,  the  «tac^  ^^^^^ 


previous  contents 
space  for  rsEult 


- — i 


I  Word 


f«turn  addresB  ,     ,  ,  , 
  I     J  by  tea 

I  -I 

I    <c-  sp 

* *  •  *  


OpenFllter 


start 

using  GlobalData 
Pttb 

pit 
PU 

pis 

«ta  atnAddr+2 

tdc 

Ida  ftyzp 
ted 

pla 
std  0 
pla 

ata  2 

idx  II 

Idy  tSia 


'  ™^  ''at:'!  to  this  banfc 
-■  save  the  return  ^ddrejs 


;  save  tlie  ROfjig 
.'  and  swap  in  outs 


;  TO"  (rat  the  pointer  co  the 
'  "IrectdirY  •htry 


f  assume  visible  and  dimmed 
;  looJt  at  the  fUetype  byte 
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Ap^en..  .  ^^^^  ^^^^ 


Ida  [01, y 
and  #?OaFr 


;  don't  look  at  the  entire  word 


BetJltfl  U 


lifSlTII 

Ktnhldr 


bna  iIotElcFl.le 
Ytix  12 

sea  1,3 

Ida  ppsave 
ted 

Ida  RtnAddr+2 
pha 

Ida  RtftAddr 

pha 

plb 

rtl 

as  2 
ds  4 


;  pass  an  all  others 

;   fihOkl  It  as  a  selECtatate  Ei%try 


;  pase  it  baek  on  the  etack 

f  point  back  to  the  old  DP 

;  and  put  the  return  address  bade 

:  restore  old  b&tt 


FiDilMflKVridtli  -  this  routine  finds  out  how  wlda  th«  window 
should  be  Tor  tha  currently  Installed  font. 


riadibKHldch 


Til  qA^jfijTp 


Start 

using  WindowData 
using  FontData 
using  ^iobsIData 

FuBhUord  fO 
_Get Font Flags 

Idy  foFlag 

Ida  m,y 
Lsr  s 

and  ISQOOl 

pha 

_SetFontFlaigs 

sti  »(ax5i}Far 
Ida  II 

sta  Llnecouncer 
anop 

FtLshWord  tO 

pMi 

phli 

pi  a 

and  » SO  OFF 
pha 

Ida  Llnecountet 

a£l  a 

tax 

Ida  Lln«TabIe,x 
pha 


^   £av^  pre^r  set  tnona/pro  flag 


;  keep  the  result  on  liie  stacit  whlla 

;  we  set  it  to  what  we  want  (as 

;  defined  by  Its  window  type  set  up 

;  wher<  we  open  this  vindow) 


;  sp^ce  for  width  result. 

;  Get  3,  polnttr  to  the  current  line, 

;  The  upper  word  is  the  same  as  the 

I  program  banl(. 


The  lotrer  word  is  stored  in  a  table. 


_£trlngwidth 
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LlneCoujiter 


pla 

cmp  MaisSoFar 
bee  Less'Than 

anop 

Inc  Llnecounter 
Ida  LlneCounter 

iJcc  Llr.eLODp 

Ida  MaxSaFar 

iidc  tio 

St a  DataWldth 

Sfttfont Flags 

rta 

ds  2 

end 


;  How  does  this  line  ccfn^ma  with  the 

;  prevlfjtja  longest  Una? 

,*  >  gr       so  save  It  as  record  holder. 

;  b«rp  current  lins 


;  Get  the  width  cf  longest  line. 

;  add  In  rocm  for  laft  and  right  margins 


f  restore  old  settings 


»  DDClosoILetn 


Close  a  window,  and  dispose  or  eictra  tSata  (In  WreEConl 

and  remove  it  frojn  window  list.     I(  no  windows,  Chen  dim  "Window" 

itronu  and  disallow  prlntlnij. 


ricCloseltejri 


Got  It 

Ttierelsona 


START 

Ufilnij  GlobalDRTA 

piifihlong  10 

_FToncwindow 

pla 

St a  whlchwlndow 
pla 

fita  w)iichwlndow+2 

era  MhlehHlndow 
bne  riierolsQne 
rtE 

PushLong  whichWlnd™ 
_C1  □  aeMJABy  W I  n  Pt  f 
bcc  Got It 


,-  Must  be  one  of  mine, 
dot  heels  Pl'SHLONG  to 

PUSKiam  whSchwlhdDw 

_GeEWreICqn 

pla 

sta  teRip^eiandle 
plx 

stx  TempZHandle+i 

Jsr  de-re  I 
sta  Q 

StK  1 

Idy  loff^ndle 
Ida  [01,7 
sta  PLcHandle 
iny 
Iny 


,-lt's  the  ffant  window  we're  deleting 
,-...SQ  get  its  GrafPortPtr 


;  get  result  for  pushing  In  a  sec, 

;  was  there  one? 

;  [jalt  now 

;  If  it  la  a  systcfa  window,  this  wlU 

;  olose  It 

;  no  error  so  doi\e 


space  tor  resqlt 
jrefcon  has  handle  to  data 

rthe  refcofi  to  de-allocate 
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Ida  [OJ.y 

Idy  tcFLag 
Ida  [01, y 
beq  Itsapic 
s^z  FlcHandle 
fit!  PicHaFKile+5 


;  tlia  plchandle  (we'll  de-allac^tet 
;  clneck  If  picture  oz  font 

;  tla,q  so  we  don't  dispose 


cLe 

sta  IDdelete 

Ida  windex 
asp  II 

bne  HaceThanOne 


;  goes  and  pulls  window  from  WlBdcnrlilBt 

;  posltlan  returned  La  a-rag, 
r   start  at  30D 
the  MenuIQ  to  d.e-sliDcate 

f  If  only  one,  we  mst  t)«  special 


pushlong  loiiglten  ;  We're  nov  dEl.etl.ng  the  only  winjdoM 

pushword  ID  ;  Isft. 
pishviord  iMindowsltenuln 

_InaertHItein  ;  add  aid  "no  windows"  menu  item. 

Fuehword  t$ODSQ  /Disable  uindows  menu 

PuEhWord  IWindowaMenuID 

_SatMenuFlag 


Lda  tTrue 

Sta  NeedtoUpdata 

stz  ErintAvail  ;  Disallow  printing 

Ida  120  ;  nut  start  loc  for  window  sizing 

St a  WxOffiat 

Ida  ill 

sta  Hyoffset 


HareThiriOTie 


Ida  IDdsleta 
pha 

^DeleteMItem 
dec  w Index 


Ida  wlndex 
beq  nomore 


1)1  c!t 


Jolt 


ata  IdCounter 
Ida  t30Q 
■ta  IBstart 
sta  ICNew 
Ida  IdStart 
op  IdDelete 
bne  Dolt 
Inc  Idatart 
bra  back 
pushword  idNew 
pushword  Id^tart 
_S«tmtenild, 
inc  idStarc 
Inc  IdNew 
dec  lescciunter 
bne  back 


Kitflsrs 


Ida  to 
pha 


(■now  delete  this  item  from  menua 


;now,  renumber  11 at 

;  THsne  left,  skip 

;  counts  huv  rnany 

;  always  the  Btarti:iq  no. 

;  will  be  first 

;  and  tha  new  one 

;  is  It  the  one  we  deleted? 

!  nope,  tjo  re-set  ID 

;  yes,  5i:lp  over  it 


;  re-caic  size 
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pha 

PushWord  IWlndowsHanuID 

_CalcMenuElze 


Pushlpng  TEripJHandle         .gel  rid  of  refcon  araa 
_DiBposeltendle 

Ida  PicHandle  .j^  it  fant 

one  dodiap 

Ida  PlcKaiidlo+2 

beq  altlpdisp 

^□Dlsp  P^shlcng  PicHandl^  rid  of  picture  a«a 

_DJsposeHandle 

sJelpDisp  PushLonsf  Whlehwlr,dc«         j^ec  rid  of  «lndo^ 

_cl(jsB*lindon 

skip  tta 

* 

^    MUlchWlndoW  and  returns  in  ^-req.  „here  it -a  position  was 

•  NQve:  it's  cptlmljEd  to  find  things  near  end  liat 

you  d  ptBfflr  ch«  athar  End,  yeu'd  need  bp™  different  logic 
tnis  raechod  seama  bast) 


Adjhlnd  Ida  Mindex 

tay 
dec  a 
asi  a 
asl  a 

sta  lOCountsr 
ad j loop  day 

^i  AdJDane 

tya 
asl  a 
asl  a 

Ida  WlndowList,x 
mp  wMchWlndov) 
bne  ad  j 1 oop 
Ida  Wlndowiiat+Z, X 
cmp  WhtchWlndow+J 
beq  shoveChK 
bra  fldjloop 

Ida  WlndowLiBt+4, jt 
sta  HindcwIisc,K 
Idi  WlndGufLlstnifi,  s 
sta  WindcwLlst+2,x 
Imi 
inx 

Inx 

ShovBChJt  epx  Id  Counter 

bne  stiovelt 
AdjDQM  tya 


Shovel t 


JdStart 

Idcemnter 

IDdeiete 


ds  2 
ds  2 
da  2 
ds  2 

mo 


J  Use  this  CO  cpunt  thru 

;  pt.  before  last  for  erd  (a-2)*4 


;<iec  the  polncor  (uniqueness  oxiscs) 


;now  shove  things  up 
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» 

t 

'  tbil  9raVB  picture  In  the  wlndpw  when  tasX  roaster  calls. 
t 

lilht  START 

using  GlobaLData 

« 

*  gee  my  own  zero  page 
t 

phi! 

plb 

ptvi 

Ida  MyZP 

ted 

*       the  ccrrect  window  port  (got 

here  Iram  within 

taskmaster) 

pustilcng  10 
_GetPnrt 
plx 
ply 

CDSHLONS  fO 
phy 
phx 
GetWrofCor 

pla 

eta  Temphandle 
plx 

stx  7empHdndle'i-2 
)9r  Deief  ;  daref«rence 

StB  D 
StK  ? 

Idy  foHandle  ;  gat  handle  to  pic  data 

Ida  [0],y 
sta  plcptr 
pha 

iny 
iny 

Ida  [01,y 
sta  pleptr+2 
tax 
pi  a 

jsl  Palrtit 

Ida  TenpHandle 
IdK  TempKandlo+2 
jar  Unlock 

pLd 
plb 

rtl 
END 
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;get  result  for  pushing  In  a  sec. 

,* space  for  result 

;  saved  the  port  here 
;refcan  has  handle  to  data 


*  Pilntlt 

*  The  routin*  whlefi  actually  does  Ehe  painting  when  passed  ttiB 

*  the  handle  to  the  picture  In  the  a  C  k  registers. 

Patntit  START 

using  GlobalData 

phx  ;  save  tliis  on  stack 

iur  daraf  jdareE.  plccurfi  handle 

sta  plcptr 
stx  plcptr+2 

PustiLong  fSrcLoctnfo 
Puahiong  fSrcReot 
Pshmor  EusKWord  to  ,-  k 

PustiWord  to  •  y 

PushMord  tO 
PPTcsPort 


copy 


jar  Unlock 

rtl 

END 

* 

*  DsGoAway  —  not  necessary  because  wa  handle  It  the  same  aa 

"  DoCloseltetR. 

w 


* 

•  DdHindQW 
■ 

■  Selects  and  showE  windovr  In  response  to  menu  selection, 

m 

DoWlndow  START 

uairq  Global IDATA 

PUSKIflNG  WilCHWINDCW  ;  select  first  so  It  only  tsdrawa 
_SelectWlndow  ;  ones 

PUSHLOffC  WHICHWimxjH 
_ShowWlndo« 

am 
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DIALOG.ASM  (dialog  boxes) 


HodgeEadgei     An  estampla  Apple  IIGS  Desktop  appLlcatlan  * 


Copyright   |c)  by  Apple  Csirputer,  Inc. 

hll  Rights  £lBa«rv«d 


ASHeseiG  Code  file  "DIALCKj .ASM"  —  Various  dialogs  taking  modal  control  • 


'  (unywindDlalag  —  Marnlng  thdt  too  meny  windows  are  open. 


(taoytflrKiDlalDg  START 

using  GlobalBata 


pha 

pushlong  lOurAlvrt 
puahlong  fSOQOO 
_CautlonAlert: 
pla 


-get  ttie  Itera  hit. 


ftttAUrt  dc  1-30, 12&, 80, 530' 

dc  1.'2374' 
dc  h'BO' 
dc  h'BO- 
dc  h"SO' 
dc  h'BO' 
dc  i4'it«iil' 
ac  I4'ltem2' 
dc  U'OOOO' 


bounds  rEct 

Id 


Itenl 


Items 


dc  tZ'l" 

dc  t2'25,32O,00,OO' 
dc  12' Buttanltein' 

dc  l4'Sutl' 
dc  12 'QO' 
dc  12 -D' 
dc  14'D' 

dc  12 '1348' 

dc  12'll,72,jaa,640" 

dc  12' StatText+SBOOO' 

dc  i4'Ksg' 

dc  12'00- 

dc  12 '0' 

dc  14 'D' 


Id 

baunds  Feet  for  button 
type 

Item  de  a  crept  ox 
It^  ^ral'je 
Item  flag 
lt«n  color 

Id 

k»unds  rect  for  message 

type  +  disabled 

Item  deacreptor 

Item  value 

Iten  flag 

Item  color 


Btrti 

Msg 


atr  •□)!■ 

str  'No  more  windows,  please.' 


End 
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*  DoAtio'jtlteii 

Brings  yp  about  box  and  waits  orXU  button  prass  until 
It  piits  it  E«3y,  sho«E  f,<,«  tfl  build  a  dialog  vindo«  by  hand. 



DaJtboutitem  STari 

using  glohalData 


ok 


Pushlong  <;34'ie-»-B 

PushWord  Myld 

PuihWofij  ID 

Fushlony  fO 

_N«tfHandle 

pla 

Pi* 

bcc  olc 

ida  ($81 

Idx  II 

jmp  CheclcDisJiError 


atx  Appl«lCDnH+2 


jst  doref 


;  get  space  for  icon 

,-  Hires  '  bytes/ line  +  rect 

;  dan'c  cars  where  It  goes 


out  of  uiBfiiflty 

Go  and  tell  ufier  error  imsta^e, 
and  use  Its  BTS  to  exit  from  inere. 


ata  0 


Cc>pyG40 

FixDBox 


lay  (0 

Ida  Appleleon6fl0,y 

sta  [0],y 

iny 

Iny 

cpy  »3q*i£+8 
bne  CapyfiflD 

Idx  f3JO-iB0 
Ida  *32a+iao 

atx  DRsct+2 
sta  Dftect*6 


;move  Icon  to  new  space 


,■  output 

;  visible 
;  re f con 

pi  a 

*ta  MDlaiogPtr 

fit*  MDlaloqptr+2 

Pushlong  MDialogPtr 
EufihWord  #1 
?ushlong  tfluttonRect 
PustiHord  1  But  torn  tern 
(■LishLong  tButtonText 


PushLonij  to 
^ughlong  IDRect 
PushWord  (True 
PuEhLong  (O 
JNewModalDiaiog 
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FushHord 
FuBhWord  tO 

_NewDlteiii 

EUShLung  MDlaloqFtr 

FUBtiLon^  lAppIelconRect 

FuahHctrd  f Iconlteni^lteinClsahla 

EuBhLonq  AppLeltonH 

EushKard  tO 

FUBhHo^d  to 

EuEhlong  to 
NewDIteffl 


PuEhHsrd  H 

Fustttonq  tTeitttect 

PusliLong  ISLartOtrext 

PushWord  lEndOfTeiit-startOrreKt 

PushSford  10 

PushLonff  ID 
KewDItem 


DdtHlal  PushHcird  ID 

PyshLong  *t) 

pla 

PuafiLarg  HDlalnqPtr 
FuBhLong  App'lelcenH 


;  chuck  the  item  hit 


DRect 

KfIil«Ic&nHect 


rts 

dc  1 "10,10, l4i,3ZO-10' 
da  4 

dc  1'135,2D,!J,0' 
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Text Beet 
Start  OtTojit 


DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
PC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 
DC 


DC  ^  °FOFPFFfFFrFFFFFFfFFFF^■FFfFFFDf■0■ 
h  ^FaFFFFFFFTFfFFf FFrFFSBFFFFFFOFS ■ 
h'0FOFFFrFFFFFFFrETFFB9f.RPrr;..SL^ 


h  .  nn^  '  " '  f^f^ff  Ff  FFFFFBBFFFFFFOFD  ■ 
h  OFOFFFFFFFFFFFrFFFFBSSerFFFFFSFO • 

M  n^r^^'^^'^'^^^f'^^BasesFFrFFFOFo  ■ 

h  DFOFFFFFFFFFf FFFFaeSBBFFFFFFf OFD . 
h ■ OFOFFFrFFFFFFFFFSffSBeSFFFFFFFOFa  > 
h  OFOFFFFFFFFFFFFFeBeBaFFFFFFFPflFO. 
H'OFOFrFFFFFFFFrFFaasSFFFFFFFP™? 
h;DFDFFFFFF8BBBFPFBJFre  IsPF^^^^p'" 

h  n"^^^^'^=«^8B8FFreaassB8SFFFa"- 

h;CF0FFFS.8aBB8ae8BaSB8BaBB8e™. 
nFaPK^^^"''^^^*^^^--'«FFFFDFa  > 

h'0FOFF=^!"^"^"^^""^"^^f'"ffP<^^0' 
s .  A^^r      ^^^^*'''=™^e^'=eeFFFFFFDFa  ' 

h  aF0FF6€666666666«66S666FFFFF™^^ 
h  DF0FF4. 44^444^4 4444fl^4jFFfFF0FS ■ 
^  °™^''^"<^444444,44441FFFFDF0' 

^DFaFFFB^^^??^r^^^^^^*'''*^™■ 

-"aF^^F^^^^=^^,^^1 --^f,^--™; 

h-aFOFFFrFUlluiuinillliFF™ 
Mn°P^f™'"^l^^^l"l"FFFF"FS 
h ■ OFOFFFPFFFl 1 llFFFFFll IIFFFFFFOFD . 
OFOFFFFFFFFFrr  tr.=-=.r.„^„„  1.  _  '  ^  ^"^^ 


Center 
■Outline 


iJM,  10,135,3^0- 

a  nap 

e -Hodgepodge '.h-DD " 


dc  c 
dc  h 

dc  h' 


dc  c'E, 
dc 

de  h-OD' 
de  c'D 


Berrss, 


-.  Hit  Chens, 
dc  h'OD- 

<i<=  c'B.  Harltfi,  D. 


8.  Koning,  s.  i^e, 


Qiii-er,  G.  ortii, 


Endorrejit 


dc  c-aiKi 
dc  ti-OD' 
dc  h-OD- 

dc  ^^^^ 

dc  h-OD- 

l^=:^J,^^^^^«'>-rv«d-,,.0D. 

dc  e-*Sya|>ato- 
a  nop 


3S6         ^p«^  ,  ^^^^ 


SuttSnBect  dc  1 '153,  ZD5,  0,  D' 
BKtonText         str  *0K" 

END 


*  SiKwPleaseWait  /  HldePleaaeWait 

•  Brings  up  a  uindcM  and  imnwdlately  puts  iresaaqe  In  it 
'  julthout  waiting  for  updace  event}. 


ShouJlesseWait  START 

using  globaLDati 

PushLoriff  »0 
Get Port 


;  aave  the  cumnt  pore 


pi  a 

St a  savflCort 
pla 

Hta  Sav«Port+2 


EushLong  tO 

PUshLong  IDiilogTejnplata 
_GfltHeuHoda  Ip  1,  a  1  og 

pla 

stii  KigHlnPer 

pis 

ata  KB7Hln?tr+2 

PushLong  MsgHlnPtr 

_Segij5CrpcLate 

_£ndUpdate 
rts 


BldePleaseHalt  EHTSr 

FushLonq  MagHinFtr 
_CloaHDlalo^ 

Self  art 


I  bagln  the  tl(pdatliig  procau 


;  hiae  the  wlndpw 
,'  csBtora  tha  part 


«sgwlnptr 


rte 
dia  4 


nlalogTamplate  inop 

dc  i- 30, 120,80,520' 

dc  1 ' True ' 

dc  H'O' 

de  U'lteml' 

dc  i^'DCOO' 


;  bounding  box 
;  vlaibl« 
refcan 
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itsml  uno-p 

dc  12-134S- 

dc  12'19, 70,200,640- 

dc  i2'StatText' 

de  14'PtEg' 

dc  1.2' 00- 

dc  i2'0' 

dc  i.4'D' 

tisg  str  'Pledss  vait  whil 

END 


;  Id 

;  bounds  ret*  tat  text 

t  type 

;  item  deECcepLOC 

;  Item  vaJi^e 

;  itaBi  flag 

;  item  color 
wb  u^t  things  up, ' 


*  HouncBootOlxk 

■  This  La  a  routine  Chat  lE  callad  whenever  the  xg/pWcatlan 

*  needs  co  get  Efunething  ati  the  boot  vcluicie  And  the 

*  boot  Volume  la  not  dn  line, 

*  This  can  occur  when  loadlrvg  fonts,  tocls  or  drlifErs, 

**-kit%titrii-k  it*  kk  kit*  ***it**tit,tt***k*ttMiiif**'^**ii-^^**-k*****  ********  ****** 

HountBootDisl!  STRBT 

_Set_PEerix  SetEraf iKPararas 
_Get_PEiaflx  GatEraf  iKParams 

PashMord  K  ;Spsce  for  reBUlt 

PtishMord  #174  ;x  pci 

PiLshWord  HO  ;y  pes 

Fuahljong  tPronjptstr  ;  Prompt  string 

PuahLQog  tvolscr  fVol  string 

FushLong  tOKStr 

FushLsflg  tCancelStr 
_TUtoiint  Vol  uniB 

pl« 

rts 

Bromptstr  str  'Please  insert  the  dlslt' 

OKStr  str  'OK' 

cancBistE  str  'Shutdjjwn' 

G'BtFnElxFftrairs  dc  1'7' 

dc  ll'VolStr' 

SEtPrEilxEarajHB  dc  1'7' 

dc  H'BaotStr' 

volstr  ds  Ifi 

Bootstr  9tf  '•/■ 
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'9 

*  QwCliToolError 
t 

'  Catiee  oysteia  death  if  A  register  la  nonjero  and  cirry  set; 

*  Ctheniise,  It  just  returns. 

i 

*  tczac  code  to  maka  pdrt  of  string  i$  la  A  register. 

*  "Mheire"  nimber  to  malte  part  of  rtrlnj  is  In  X  register. 
• 


QwdiTdCilErrgr  START 


OuthHaq 

CedM 
EndMsg 


rtfl 

pha 

pea  0 
pea  0 
%>hx 

Haxlt 
pla 

Qt?  evades 
pla 

St a  codes+Z 

pla 

pha 

Pushlflng  tC^iiChKsg 


I'lf  a  tocl  error  didn't  hiappen 
;tlien  just  return 

I'Save  error  coda  for  now 

;  Convert  the  "ifhere"  debug  trace 
{ftupiher       s  four-dlfllt  ASCII  he* 
; string . 


iRestora  error  code 

;EKlt  tn  aystera  failure  handler 
I  (bouncing  apple) 


anop 

dc  ll'EndKsg-StartHsfl' 
de  c"  At  S' 

dc  c' f  Could  not  handle  error  S* 
anop 


Em 


CheexclslcErrDr  —  Display  stop  alert  dialog  if  ProDOS  error  happened. 

We  sniff  the  A  register  to  see  If  an  error  occurred, 
and  assume  the  X  register  to  be  loaded  with  a 
"Hhare*  value,  used  to  locate  bugs. 


t^*t **************** 


OeokSlsJcErroF  START 

using  slobalData 


phx 
pha 


;  Save  the  VHiere  value 
f  save  the  error  number 


InltCursor 


;  Sot  pointer — looks  better  than  watch 


pha 

PuBhlJong  lOurErrstr 
PkjfiJiWord  14 
Int2Hes 


;  Restore  the  erro-f  number 

;  Convert  the  error  message 

;  to  an  ASCII  string  4  chars  long 
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pl> 
pha 

rushLong  lomwherestr 
FushHard  (2 


Do  this  juat  for  clarity  jnoca  that 
Vheis  value  is  already  on  EtacJ![) 
Convart  the  Whero  value 
to  an  ASCII  strins  2  chats  long 


pushLonQ  IDurAlert 
pushlpng  isClClDD 
_stopMert 

aec 


space  for  result 

folntar  to  tamplata 

standaFct  filter  procedure 

Drav)  box  and  wait  £cr  mouse  OK  press 

Get  the  Item  hit  (the  DK  button) 

Set  the  error  flag 
Return  to  caller 


OurAlert  dc  1 ' 30, 120, BO,SZ0" 

dc  i'6666- 
dc  h'BD" 
dc  h'SD' 
dc  h-9D- 
do  h'SQ' 
dc  H 'OKButton' 
dc  14 ■ Message ' 
dc  H'OOflE)' 


bounds  rect 
id 


OKQUttOO 


KasBage 
ErrKsgECr 


dc  12- !■ 

de  i3'!5,320,(10,00' 

dc  12 'Buttonltem' 

dc  14-OtU4wne' 

dc  12 '00' 

ttc  U'Q' 

dc  H'O' 

dc  12'134B' 

do  12' 11, 7z, jao, SflC I 

dc  12'StatTeXt+$BOO0' 

dc  14'M«g' 

dc  12' DO' 

dc  12»0' 

dc  14 '0' 


Id 

bounds  rect  for  button 

type 

Item  des crept Df 
Item  value 
Item  flag 
Item  color 

Id 

teund£  rect  for  static  text 

type  *  disable  flag 

Item  ds£ crept or 

item  value 

item  flag 

Item  color 


Btr  'OR' 


Hsg 

StartMsg 
DuxErrStr 

OurWhereStr 


Cndtteg 


dc  ii'EndMflg-startKeg' 
dc  c'Diak  error  ?' 
ds  4 

ac  e'  DCdUrrEd  at  $' 
da  2 
dc  c ' , ' 
dc  h' Dd" 
a  nop 
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FONT.ASM  (fonts) 


* 

KQdgePOdlje:    An  example  Apple  IIGE  DssKLcp  apjplicacior  ' 

* 
* 

CQpyright    (cl   1986-87  by  Apple  Cnmpuler,  Inc.  * 
All  TliqhtH  Reserved  * 


A£MESai£  CadE  ^tJE  "Four. ASM"  —  Choose  font,-  diaplay  font  wlrdow  cDntents  • 


********  **i***#*#a*  +  **c*********tt******td****«A**«»*i(t,*h****««A 
♦ 

i 

•  «*I**«A**±*********************»«***»*^C*I:**A***********  **■««■,* 

roffitDHTfl  DATft 
PwtWlnPlr  ds 

Desliedront        dc  iA 'SOSODFFFE'  f  Syatem  Font  alie  8 

HoroHag  dc  J2>0*  ;  start  nut  showing  proportional 

CLrFortlnfo  a  nop 

CFAscene  ds  3 

CFDescent  ds  2 

CFttaxKld  ds  2 

CFLeadlng  ds  2 


CurHeight  ds  2 

UiieCountor       ds  2 

Cur?os  ds  4 


LlneTible  dc  1 '  LlnoO, Llnel,  Line?, Llne3, Llne4 • 

dc  i-llnBS,Llne6,  Line"?,  LineB, LlncS' 
de  I'linelOiLlnell,  Llnel!,  Llnel2,I,lnel2' 

Lined  ds  30  ;  man  name  len  is  35  +  1  far  length 

I  ;  snd  A  tor  slie  info 

llnel  str  ■ ' 

line!  str  -The  quick  brown  fuK  jimpad  over  the  Ujy  dog.' 

LineJ  str  'She  sells  sea  shells  down  by  the  sea  shore.' 

llnel  str  '■ 

Lln«5       dc  h'2!>' 
111;  h'DO  01  02  03  D4  fla  D6  07  OE  09  OA  OB  DC  DD  QE.  OF' 
dc  h'lO  11  12  13  14  IS  16  17  IB  19  lA  IB  IC  ID  IE  IF' 


I 
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LJne£    dc  h'20 ' 

dE  h-20  21  22  23  24  2S  if  27  2B  S9  Zfl  2B  2C  ?D  Z£  2F' 
h'3(J  31  32  33  34  35  36  3T  38  39  3A  3B  31  3D  3E  3f' 

LlreT    do  h-20' 

HMD  41  42  43  44  45  4S  47  4a  4&  4J(  4B        4D  4E  4F- 
dc  h.50  51  52  53  54  55  56  57  58  59  5A  53  5C  5D  5E  5F- 

LlneB    de  h'20' 

d=  h-SD  61  63  M  65  Ss  67  Ba  69  SB  6C  6D  6E  (.F- 
dc  h  7a  71  72  73  li  75  76  77  7B  IS  7A  7B  7C  7D  7£  7F> 

Lines    dc  h"20  • 

dc  h'BO  Bl  82  B3  B4  E5  S6  B7  88  B9  8a  BS  BC  BD  8E  fi^^' 
dc  SI  92  93  94  S5  9€  97  9g  99  SA  9B  9C  9D  9E  SF- 

LlnelD  dc  h'20 ' 

d=  h-AD  M  A2  A3  A4  AS  fl6  A7  AS  A9  AA  A3  AC  AE  AE  AF- 
dc  hiB^.  Bl  B2  &3  B4  B5  B6  B^  &9  B9  BA  &B  EC  BD  HE  BF- 

LlriKi:  de  h'20 ' 

flc  h-CO  CL  C2  C3  C4  C5  C6  C7  CB  C9  CA  CB  CC  CD  CE  CF' 
dc  h-DO  Dl  D2  D3  C4  D5  D6  D7  D6  D9  DA  OB  DC  CD  DE  DF- 

dc  h-EO  El  E2  E3  E4  E5  E6  E7  EB  ES  EA  EB  EC  ED  EE  EF- 
d=  h-FO  Fl  F2  F3  F4  FS  F6  F7  FS  F9  FA  Fa  FC  ED  FE  FF" 


END 

•  until. («,,»,, 


DoChoogeFont 


DoChooaeFont  START 

uslnij  GlobalDATA 
using  FontDATA 

JSetPort 

Pusfiliiji^j  ITempPort 

^     ^.      ^  ;   apiCB   Tor  resglt 

PuahLong  DesiredFont 
PushWord  tO 
_ChooseFQnt 

Ida  l,s 
ora  3,s 
bne  ItChanQed 

pj^  '■  chcmseFont  retutnsd  3  oODa,  so  the 

*^  ;  font  hasn't  changEd 

Puahlong  iTempPpit 

f*^  ;  bad  return 


pla 

sta  DesiredFone 
PI  a 

sta  DeslredFontt2 

PUsbwcrd  to  ,„„  , 
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fushlong  IS_Fnaire 

_Oel;Fa.nlnfia 

pla 

Ida  DesiredPnnt+J 
and  ffOI^Fr 

pfta 

Ida  »''B,_F[lanie 
plia 

Ida  R  Ffdme 
and  tSOOFF 
Luc  a 

adc  »[V_FName 
phi 

PushVtord  •<! 
PushVford  10 
_Iiit  2Dee 

inc  a 
inc  a 
Inc  a 
Inc  a 

sta  H_FNaine 
PushLong  tTarpFort 

Set  Port 
clc 


I'lgrore  re  suit 

,*         font  size  in  a  r^g 

;  high  word  of  polntftr  to  name 


;  low  word  of  pointer 
;  cutput  lengtli 
;  fiot  signed 


;  bump  tha  length 


;  Blie  of  graph  port 


ImpPort  d*  ?AA 

HID 

•  DlspFontWlndow 


Di»pFDntMl.nd.(™  STABT 

using  Font DATA 
using  Glob^iD^ta 


get  my  own  ^ero  page 


phb 
ph): 
plb 

phd 

Ida  HyZP 

ted 


•  got  the  csarrant  window  port  (got  her*  from  wlttiin  taakjjiaster) 


FONT.ASM  (fonts) 
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pusjilong  10 

pin 
ply 

PUSHIyOHG  fU 

phy 

Pluc 

_aatl(fBefCon 
pis 

sta  Tefflphdndae 
pix 

stK  TeirpKandle+z 
Jar  Dorer 
atx  2 

Idy  lQFontlc+2 

Ida  iai,y 

tax 

day 

day 

Ida  [a),y 

jal  ShowFont 

Ida  TerapHandla 
IdK  TanipHandle+2 

pUa 
ztl 
END 


.'set  rEsult  for  pushing  In  a  sec. 

;  space  for  rasult 

;  sivtsj  the  port  hat* 


;  de  referance 


;  gat  the  font  ID 


•  ShowFont 


•  Cmmoji  routine  to  actually  draw  the  cortanta  of  the  wlndnw 

in  :haTi"x"       r."^'  ^''^  "  in  tn^ 

*n  cne  A      X  ragieters. 

± 

ShosfPont  START 

using  SlobalData 
Using  FontDat^ 

pha 


pdix 
pha 

PuahHoTd  fo 
^installFoiTt 

PushLong  ♦Current Info 
JsetFontlnfii 

■ti  Llnecounter 
elc 

Ida  CFAscEiit 


f  save  copy  an  stacH 
;  Install  the  font 

?  Oot  Its  size  Info 

:  lero  the  line  counter 

;  calculate  the  line  separation 
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adc  CFDeacent 

sts  curHelght 


PuahWord  iO 

jiavaTo 

pushwcrd  tO 

FushLonq  tLlneO 

_G»tFiimInro 

pla 

pla 

and  * SO OFF 
pha 

Ida  ** Lined 
pha 

Ida  LineO 
and  4300Fr 
ins  3 

FustiHord  ti 
FLLBhwasd  10 
_lrLt,2[5Bc 

IdA  LlnfiO 
Inc  a 
inc  a 
Lnc  a 
Inc  a 
it a  LineO 

_B*Cfontriigi: 

Ida  [OJ,y 

and  ISOOO: 
pha 


LineliDBfi  ar.Dp 


EushLo-ng  tCuiFos 
_GetPen 

PuatiWord  f  b 
Ida  CurpQS 
clc 

adc  CurKalght 
pita 

_Mov«To 

Ida  LlneC4Unt«r 

tan 
phk 
phlt 

Ida  1,5 
and  fSOOFF 

$ta  1 ,  G 


;  start  the  pen  position  at  0,0 


f  get  font  Id  off  stack 

;  space  for  result 

;  fanlly  nu-nber  was  in  « 


;  ignore  result 

;  tiigh  word  of  font  Id 
;  stiB  In  high  byte 


;  high  word  of  pointEr  to  nanse 


;  loM  motd  of  pointer 
;  output  length 
;  not  signed 


;  bump  the  length 


sava  prev  set  nono/pro  Hag 


Jceep  the  result  on  ths  »tack  w^iKb 
we  set  it  to  vba.t  we  want  (as 
defingd  by  Its  window  type  set  up 
when  we  opened  this  window) 


;  get  the  current  position 
,*  reset  x  position 

;  and  y  position 
;  draw  current  line 


FONT.ASM  (fonts)  365 


lili  LineTible,K 
pha 

^Drawstring 

Inc  LlneCounter 
Ida  LlnECounter 
mp  INiMLLlnes 
bct^  LineLaop 

rti 

EfTD 


;  bump  current  line 


,■  restore  Itqwi  savsd  position 


Change  TpMoriD 
FushID 


START 

using  FontData 
Using  MenuData 

Ida  KonoFlag 

Bti  MonoFlag 

beq  ChangeToMono 
PiishLonq  (PropStr 
bra  PushID 
Pushlong  I Mono St ( 
PushWord  tMonoID 

SetMItem 
rtfl 


/Change  nessage  to  show  effect  In 
,-H£XT  ssleqtion  of  this  ijenu  Item 
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PRINT. ASM  (printing) 


»  * 

*  HodgePsdgs:    An  flxample  Apple  IISS  Desktop  application  * 


Copyrl^hc  (c)  19Se-S7  by  Apfile  Ccmtputer,  Inc. 
AIL  Rights  Reserved 


^      ASH65ei&  code  file  'P&IST.ASM-  —  Print  dialogs;  Print  Manager  calls 


♦  DtChws&rltem 


'  Thi»  Is  the  rsutlns  tti«t  Imnilles  the  CtiooH  Printer 
*  Mm  It*™. 


DoChccserltffla  START 

using  GlcibalData 

PushWord  10 

_PrCtiooser 

pla 

rtB 

EINS 


'  DoSetupIten 
ft 

*  This  ie  Che  routine  that  handles  the  page  setup  Item. 

BoSetLiptten  START 

using  SlE^lData 

Ida  Print Re cord 
ora  PrlntBecord+I 
bne  AlreadyThere 

jsr  Setufjlefault 


AlreadyThere      a nop 
pha 


pushxong  PtlritBecord 

_Pi:Valldate 

pla 

Euehi«Ord  tO 
Puehiong  PrlntBecord 


PRINIASM  (printing)  367 


_prSti Dialog 

Its 
END 


*  SetupOelault 
* 

***  •♦"*.*•*....♦....*  

SHtupOefault  START 

Using  GlobalDATA 

PuahLong  (O 

Puahuord  KylD 
fuahWord  (SBQla 
PufiJiLong  10 
_neuH^ndle 
pla 

■ta  PrintHecord 
pi  a 

St  a  PrlntBacDE-d+J 


AltB«dyThBre 


Puehl/ong  PrlntRacard 
_prdeJault 


*  DoPrlntltBai 


•  Till  f^^""^  1" 


DoEfintlte 


STflHT 

using  SlobalData 

pha 
Gat Port 


;  get  ttie  cuiTent  |>ort 


pha 
pha 

^FrontWlndow 
pla 

rta  WlndowToPrlnt 
PU 

at  a  tflT!dowToPrint+2 

ora  KlndowroPrlnt 
bne  SoniBthlngroPrlnt 
brl  Sltlplt 

StmethtngroPrlnt  anap 

Ida  PrintHeoord 


;  first  Ma  if  there  la  a  window 

;  to  print. 

;  and  Save  pointer  to  It  now 

,-  before  any  dlaloge  are  dlspl^yodJ 
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ora  PrlnLH6(;ord+2 

pha  ;  spatra  for  result 

EushLong  PrintReeoid, 

pla  ;  ignore  result  slrice  all  Is  viell  now 

PuihWord  (0 
PushLonij  PrlncHecord 
_ErJobOialog 
pi  a 

bri  sklpit 
ctntinuo  anop 

_WaltCTirMr 

FuEhLong  FElntRncord 
PushLong  tO 
_PrOpenDoc 
pla 

Eta  PflfitPOjrt 
pla 

sta  PrlntPoiT+I 

PuahLonij  PrlntPart 

_PrCipEnPagE 

jsf  QrauTopWlndow 

PuBhLonfJ  prlntPort 
_PrClo3iPaije 

PushLong  PrlncPort 
^PrClnaeDoc 

PushLong  FrlntRscord 

Push Lang  iD 
PrPlcFiU 

_I  flit  Cursor 

Sklpit  a nop 

_SetPo£t  ;  restore  original  pott 

rts 
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OrswTopWlndoH  START 

using  GLsbalDATA 

Pha  ;  space  tni  result  of  BBtMRefcon  call 

pha 

PuihLong  WlndorfToPrl nt 
_GetHHefCon 

pla 

sea  TheHefCon 
plx 

StX  ThSRerCqin  +  Z 
jsr  Dersf 

Idy  foFlaj 

[01, y 
beq  LTsaPalnt 


Idy  *oFQntID+2 
Ida  [Oj,y 
tax 

day 

Ida  t51<y 
3 si  ShowFont 

bra  AllI>on$ 

DseEaint  anop 

Idy  ;  get  handle  to  pic  data 

Ida  t01,y 

tax 

dey 
dey 

Ida  [01, y 
jal  Palntit 


AllDone  Ida  TtieBsfCon 

IdK  TheHefco/i+i 
jsr  Unlock 


theHerCon  ds  4 

MlndoMToPrint  ENTHy 
ds  1 


Gtn> 
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10. ASM  (pictures  and  files) 


Had^Ef od^e:    An  Example  Apple  IIGS  Desktop  appllcAtion 


Copyright  tc)  ISae-BT  by  Apple  Computer,  Inc. 
All  Rights  Reserved 


ASHeseiS  Code  file  "lO.ABM"  —  Picture  Load  and  Save  stuff  calling  ProDOS 


4 

»  LdacBne 

*  Lsads  t,he  picture  whnse  path  name  is  passed  In 

*  to  tEldress  pasHd.  iji 

*  FlcDestlN 


LoadQr.a  srAKT 

using  lODita 

_0?£N  OpenParama 
bcc  contl 
jmp  Errorl 

nesatl  a  nop 

Ida  QpenID 
sea  ReadlD 
sta  ClQselD 


_READ  ReadParams 
bcc  cent  2 
jmp  Errorl 


clc 
rts 
end 


IO.ASIVI  (pictures  and  flies) 
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*  5avfl0ne 
* 

•  Saves  Che  picture  whose  pith  name  Is  pasBeii  in 

NamePtr 

'  frojc  address  passed  in 

'  PicUestOUT 
* 

Saveone  START 

using  lOData 


Ida  Nan^Ptr 

sta  NameD 
Ida  NamePtt+Z 
sta  NaraeC+Z 
Bia  Najfieo+z 


Destroy  DestParams 


ContO 


cents 


sta  CType 
Ida  ICi 
sta  CAuK 

Create  CreatePaims 
bee  contO 
imp  Errorl 

_OPSM  GpenParaiSB 
bcc  contl 
jiBp  Errorl 

anop 

Ida  OpaniD 
sta  Wrltein 
Eta  Clas^ZB 

_WflTTE  WriteParaiq^ 

bcc  eo-ntj 
Jmp  Errorl 

a  nop 

ClOHB  CloieParaniH 
dc 
end 


;  SuperHirea  pictura  type 
;  standard  type  -  D 


....  1....,,,,,  

Errorl  —  handle  disk  error  during  read  or  itrite 


Errorl 


STftRT 

using  lODaCa 
pha 

_Close  Ciose?aram» 
pi  a 

jsr  CdeckDlfilc  Error 
rts 
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GLOBALS.ASM  (global  data> 


'  t 

'  HodgeFodge:    An  aMiiipl«  Apple  lies  D^aSctDp  ^ppllCdtlon  < 


Copyright  (c>  1986-87  by  Apple  Cdmputer,  mc, 
All  Ellghts  Haserved 


•   k^esaiS  Code  file  "GLOBAIS-ASH"  —  Global  variables  sntj  raise,  routines 


* 

*  SlotMlOATA 


********  ft**  t»mtits.mm»t****t****t*t*i,t***tfn,tn,*t'1r1i**ftttt*tm 

SlcbalData  QA1A 


ttoffset 
Byoffaat 

nullBfict 

»ply 

JLtype 

r^iujayp 

r_fiq4me 

r_rullpn 

QulCParuts 


do  il'lS'.c'Lead  which  Pirtura:' 

dc  11 '19' ,c' Save  which  Picture;' 

dc  I'JCl"  ;  offset  for  upperleft  window  corner 

dc  I'l!'  ;  offaet  foi-  upperleft  wiridoH  corner 


dc  i-O,n,0,a' 

ae  li'D' 
dc  12 'D' 
de  ifi 
ds  12B 

dc  14'0' 

dc  i-$4flOCl' 


jSi-  OET/EUT  FILE  leooxd 


am  restartalBle  In  mamory 


t  Tool'Tablfl 

f 

■f 

f 
f 
f 


f  Thi$HDde 


dc 
dc  i' 
de  i' 
dc  1' 
dc  i 
do  1' 


dc  1 
dc  1 
dc  1 
dc  1 
dc  1 
dc  1 


l-ll- 
4,50101 ■ 

6,  $0105' 

14,50103- 

15,!CI103' 

16,50103' 

20,S0100" 

21,50100' 

J3,$01DO' 

J'!,?!J100' 

28,50000' 


do  i'SOOBO' 


((UiCledraw 

desk  cnanagec 

event  nsanaijer 

ulndQH  nianager  from  disk] 

menu  manager  from  Dislcl 

control  manager  farm  diak! 

Una  edit 

dialog  manager  Iran  disk! 
standard  files  from  disk[ 
Fant  irarsager 
List  ir>anag«r 

;lnit  noda;  £4Q 


SrcUicInfo 
StcKr 


do  I'SflO' 
da  4 


;PPtoPort  640  patms 


QLOBALS.ASM  (globo!  data) 
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dc  i ■ISO' 

de  I'D, 0,200,640' 


Srcllact 


dc  I'O, 0,200, 640' 


Event Rflcord 

Event HaES age 
EvantHhen 
EventMherfl 
EwentModlflsT 


ds  4 
ds  4 
d«  4 
da  2 


TasltDATA 


ds  i 

dc  n'sofFr' 


OuitFlag 
H index 
MyZP 

i  ZpMandle 
;  My  ID 


ds  2 

de  4 

da  J 

gequ  15 

dE  2 
d£  4 
ds  2 


t Index  to  nent  avail .window  ID 
; Manlmiiiii  number  of  windows  open 


Vlndex 

da 

2 

Vtable 

ds 

16*4 

Window Llit 

ds 

16*4 

SfhichWlndow 

ds 

4 

TatspFfsndl* 

ds 

4 

Teii!p2HandlB 

U« 

4 

tic Handle 

ds 

4 

Save Port 

ds 

4 

SavoType 

dE 

ActlvateFiag 

ds 

2 

NeedToUpdaEe 

ds 

2 

ThlsWType 

4s 

i 

Lastwtype 

ds 

2 

PrintAvali 

dc 

I'D' 

PrlntBecord 

da 

4 

PrlntPort 

ds 

4 

VolNot Found 

;  MyWlndowInfo 

;  This  is  the 

dat^ 

structure  usad 

;  allocate. 

MaxNaiseSlze 

equ 

29 

QHandle 

equ 

0 

oBlanJt 

^  J 

oHandle+4 

equ 

oBlsnk+l 

oKame 

oqu 

oLength+l 

oWStufi 

equ 

oria^ 

equ 

ol«StuEf+6 

o  Extra 

equ 

oFlagtl 

oFontlC 

aqu 

oHandla 

;  Index  UBBd  to  list  of  what  WiS  visible 
;llflt  nf  wh«t  tiXS  vIb.  when  Hldinij  all 
;all  windows  handle  go  Into  this  list 
,'wlll  contain  window  pointer,  cur.  window 
faane  tatja  handlos 

;  handle  to  picture  data 

(■Save  current  port  onv  for  SticmPlHalt 

(■flag  for  checJc  front  window, 
;used  to  prevent  multi  menu  redraws 


;Kaka  sure  this  starts  as  0 

;  handle  to  print  record 

;  pointer  to  print ing  GrafPort, 

;  prodos  error 


iKTgaat  name  we  allow 


MyVfififoSlie 


,-  If  the  type  la  for  font, 

;  the  first  Held  is  a  FOntID 

;  tiithar  than  tha  hatidle  to  picture 

;  data. 


equ  ciE)ttra+4 
END 
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*  ICData 


ttMtePamw  amp 


CTVIw 


dc 
sic 
dc 
dc 
dc 
dc 


14'0' 
i2'SCI006' 

14'soooooi;eo* 

12'SOtJO0' 


DRNMH 
BIN 
Auk. 
type 

create  date 
create  time 


dc  t4'0' 


MBsPtr 


d3  2 
da  i 
4 


liaadParams 


?REadTD 


2 

ds  4 

dc  14'SB00D" 
As  4 

a  nap 
ds  2 
da  A 

d9  4 
ds  4 


f  this  many  bytes 
f  fww  many  xfered 

;  far  readlnq  a  paclied  file 


;  this  luny  byte* 
;  how  [nany  ufared 


CurrantHark 


ds  2 
anbp 
ds  4 


HrlteFaram 

WrltelD 
flcpestouT 


ds  2 

ds  4 

dc  i4-SafJ0[!' 

ds  4 


f  tnls  (iwriy  bytes 
;  hovj  many  xfersd 


ClaseParaFj 

ClCESlD 


a  nop 
ds  2 


GLOBALS.ASM  (gfobal  data)  375 


* 

*  Does  not  do  a  whole  lot . 

nn.mit4,,j»,  ^^4,^,,,,^, ,,,,,,, 

Ignon  START 
END 


*  Dvraf 

i 

*  Derefa  and  locka  the  handle  passed  In  a,x.    Besult  passed  baeli 

*  In  Treshes  Q  cn  zp. 

Deref 


START 

£Ca 

D 

3tX 

2 

Idy 

14 

Ida 

10], y 

ora 

(SBQBO 

sia 

dey 

dey 

Ida 

tlx 

Ida 

fO] 

rts 

EHD 

•  (Jnlcck 

*  trnlocliB  the  handle  passed  In  x  and  a,  0  1*  traahfid  on  fa 
■ 

Unlock  START 
sta  Q 

idy  14 

Ida  [01, y 
and  t$7FFT 
ata  [Dl,y 
rtj 
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Appendix  F 


Hodgepodge  Source 
Code:  C 


HP.CC  37a 
MENU.CC  382 
EVENT.CC  305 
WINDOW.CC  390 
DIALOG.CC  400 
FONT.CC  405 
PRINT.CC  409 
HP.H  411 


377 


HP.CC  (main  program) 


*  Hodgepodge:  An  cxaicple  Appld  IIG5  Desktop  ■Epllcation 
« 

♦  Wrlttan  by  the  Apple  riGE  Dftvalopmant  Team 
« 

•  Cspyrlght  (c)  19BS-H7  by  Appla  Coiiiiut»r,  Inc. 

*  All  Rights  Reseivad 


This  program  and  its  derivatives  are  licensed  only  lar 
UEe  on  Apple  <=i:)inputars. 

Works  bised  on  this  program  must  cn-ntaln  dnd 
conspicuously  display  this  notice, 

rnls  software  is  pravided  (or  your  aval uat Ion  and  to 
assist  you  In  developing  eoftwarre  for  the  Appla  IIGS 
COtnputer. 

This  is  not  a  distribution  iiCEiiae.  Distribution  of 
this  and  other  Rppla  Bofcware  requires  a  fieparace 
license.  Contact  the  saftusre  Licensing  DepartBent  of 
Ai:ple  CDmputEr,  Inc.  for  detallji, 

DISCIAIMEa  OF  Mahhanty 

THE  SOFTHABE  IS  PROVIDED)  -AS  IS"  WITHOUT 
WARB.WJTT  OF  ANY  KlUD,   EITHER  EXPRESS  OB  IMSLIED, 
VflTK  RESPECT  TO  ITS  HERCHANTA&IlItf  OR  ITS  FITNESS 
FOB  AMT  PARTICULAR  PUHfOSE.     THE  EHTIRE  RISK  AS  TO 
THE  QUALITY  AWD  PERFOBJtHJCE  CF  tHE  SOFTWARE  IS  WITH 
YOU.     SHOUtO  THE  SOFTMARE  PROVE  DEIFECTIVE,  YOB  (AMD 
NOT  APPIX  OR  AN  APPiE  AUTHORIZED  REEHESENTATIVEl 
ASSO>!E  THE  ENTIRE  COST  OF  ALL  NECESSARY  SERVICING, 
REPAIR  OR  CORRECTION, 

Apple  dees  not  warrant  that  the  functlofiH 
contained  in  ths  Sortware  will  meet  your  rflCjuireiiEnta 
pr  that  the  operation  of  the  Software  will  be 
uninterrupted  nr  error  free  or  that  defects  in  the 
Software  will  be  cortected. 

SC«E  STATES  no  NOT  ALLOW  THE  EXCltJSION 
OF  IMPLIED  WARftANtlES,  SO  THE  ABOVE  EXCUUSIOM  MAY 
NOT  APPLY  TO  rm.     TTIIS  WAKAAHTY  GIVES  YOU  SPECIFIC 
LEGAL  RIGHTS  A«D  YOU  HAY  ALSO  HAVE  OTHER  RIGHTS 
WHICH  VARY  FRCM  STATE  TO  STATE. 


Source  file  HP.CC  —  Startup  and  shutdown  routines 


tifipJude  <types.h> 
tincliiflE  <prodoB.h3 
♦  include  <niifictool  .h> 
f include  <:qalckdraw.h> 
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Ida  <qdauK.li> 

ide  <windc}H.h> 

ide  <iseniory .,  hi 

Ida  <(llalog.h> 

ide  <nienLi,h> 

lie  <control,l!> 

ide  <deslt.li> 

ide  <:aveiit.h> 

Ida  <:llnaeciit.h> 
ide  retool 

ids  <It9catcr.h> 

Ida  <stdflle.h> 

;da  <pj-lnt.h> 

:da  cf  ont .  h> 

ida  <intnisth.h5- 

ide  <llst  ,h> 

jde  <scrap.h> 

jde  "hp.h" 

".am  Int  toolErrf 


=l«ii  ToolsFounii         -  FALSE, 
HI 10k  -  FALSE, 

FManagerFound    -  TRUE; 


HylD; 

Int  ThisMode 


/*  Do  we  have  topis  J  •/ 

/*  asauna  the  PK  is  theca  */ 

/*  Init  mode  -  64a  */ 


iht  ToolTstile  []  - 

4,  QxlDO, 

5,  0x100, 
£,  OxlDO, 

14,  0x100, 

15,  0x100, 

16,  0x100, 
IB,  0x100, 

19,  0x000, 

20,  0x100, 

21,  0x100, 

22,  OxlOD, 

23,  0x100, 
27,  0x100, 
2S,  0x000); 


/*  Number  of  itenis  */ 
/*  QulcltDrav  II  ■/ 
/•  DEBk  Manager  •/ 
/'  Event  Hanager 
/*  Window  Kandtjer 
/'  Menu  Manager  •/ 
/'  Control  Manager  */ 
/•  QulckQraw  Rusillarsf 
/•  Print  Manager  */ 

Line  Edit  •/ 
/'  Dials?  Kanaijer  */ 

Scrap  Manager  */ 
/•  stanaara  File  */ 
/-  Font  Manager  */ 
f*  List  Managar  •/ 


r 

/*  This  ia  thfl  routine  that  will  do  the  Init lallicat tots  ai  tools,  will  allpcata 
maisefy  and  all  relatatl  casiiB 


t 


static  char  EysToolsDirStr  [1  -  "NpVSYSTEM/TfWLS"f 
Btatic  FileFlBC    ParajnSlock:  -  (  SysTiKilsDlrStr  ,  NULL  ],- 

TLStartup  t)  ?  /*  for  calling  tool*  •/ 
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ChacjETwlError  [1); 


HylD  -  MMStartOpO; 
ChedtToolError  {2i ; 

MTStartUp  0  ,- 
CtieckTeol Error  (3) ; 

y  -  NeHHarLdl.e  (OxBODL, 
«ylD, 

attrBank  + 

attrriKed  + 
attrLoclted, 
OL)  ; 

ChedtTOolErrcir  ( <  l  ; 


/•ID  for  all  transactions  V 


/*  Misc.   Toala  •/ 
Hake  sure  all  Is  oK 


Eleven  pages 
/*  put  It  to  ray  name 


/'  don't  care 


a  -  *y;  /*  deref  handle  */ 

QDStartUp  (  (Int)   i,ThisModB,MAXSC3W,MyrD)  f 
CtiecltTool Error  (5) ; 
orlgPart  -  CetPort  Ut 

EMStartUplUnt)  z  *  QnJDO,  20,0,  64D,  a,  XOO^MylD) ;  /'  Event  Manager  •/ 
cbecJtTOOl Error  (61 ; 


MoveTo  120,20); 

SetBacXColor  (01; 

SetForeColor  (15); 

Drawstring  ("\pOn»  Moniflnt  Please,,. 

Showcursor  (); 


GEr_riLE_lNFQ  (iPaKMBBlocIt) ; 
if  (_tot}lErr) 

if   (HoubtBootDlsS!   (1   —  1) 
goto  Trv Again; 

else 

murn  (false); 


Loadroo Is  (TaolTable); 
ChecleTootError  (71 ; 

QDAuxStartUp  Of 
ChedcTool Error  (Bl ; 

Ha  It  Cursor  (1 ; 

HlndStartUti  lMylD>; 
CheclcTool Error  (91 ; 

RafrestiDeBktop  (NULL)  ; 

ctlstsrtUp  (MylD,  tint)  i  +  0x40(31; 
ChecltToolError  (10); 

LEStartup  (HylB,    (tnt)  i  +  OkSDO) ; 
OieekToalError  (11); 

DlalogStattOp  (MylD); 
CheckToolError  (12) ; 

ManuStartnp  (MylD,  tint)  z  -i-  OxEOD); 
CJiecltreolError  (13} ; 

DeskStartUpO  ; 
ChacktoolError  [14)  ; 


/*  Exit  function  unEuccess fully  •/ 
Haw  It's  ok:  to  do  this  */ 


/*  Shau  wristwatch  cursor  */ 


/'  All  we  n&ad  is  init'ed  now  '/ 
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%iaHplKi£eMalti  (),' 


SFStirtUp  [MylD,    [intl   z  +  3jc7CJ0); 
ChedtTool Error  (1.5); 
SrULCaps  (trufl)  ; 

FHStsttUp  (MylD,    tint)  i  +  CiiHDD)  ?  /*  tha  watch  cursor  is  up  */ 

CtiackTool Error  (16);  /*  while  we  count  the  fonts  *! 

Lljtstartup  Of  /*  j!<  Note,  not  ListstartUp  Mlth  upper  case  "U"[  •/ 

Cto  d(  Too  1  Er ror  (1  ^^ ; 

SCHpStartUp  0; 
ChedcIoolError  (IB) ; 

PttStartUp  (KylD,    (Int  )  z  +  0*SCiD] ; 
ChedcTool Error  ,■ 

HldeHeaeeHiiit    (I;  /■  Hemove  dialog  bOK 

InltCursor  (j;  /"  Show  arrow  cursor  */ 

r«tu™  [true);  /*  Exit  function  luccassfully 


SbutDoHD tools  {I 

I 

DiiliShutDown  (); 


If  tVindStatcs  0  '.- 
HideAlLHlndowa  I),- 

LiitShutDown  [) ; 

pHShutDown  (I; 

SctapShutDown  ( )  ; 

EHShutDoHr  (); 

SFShutDown  Of 

HenuShutDowTi  ( I ; 

DlalogShutDown  |)f 

IiE£huC;[>own  | ) ; 

CtlfhutDown  0; 

Hlr.d^tiutDcHTi  0; 

QDAuxShutE^wn  Of 

EMShutDown  | ) ; 

QDShutDown  ( ) ; 

HTShutDown  | ) ; 

If  (MMStatus  0  !-  OJ 

i 

DlspoeeHandle  (yj  ; 
HMShutDoHn        iMylDI ; 

} 

TLShutDcwn  |); 


/'  HUH  pfO^fam  rcuttns  */ 

main  (] 

i 

if  (StartlJpTools  0)  ley  to  Initlsllte  tools  -/ 

i 

SetUpMenua  ||; 
Main£v«nt  Of 

) 

ShutDownTools  ();  /*  shUtaDiirn  tools  even  If  didn't  run  '/ 


HP.CC  (rraln  program) 


MENU.CC  (menus) 

^  Hodgepodge:    AJi  exanip:e  Appie  ncs  Desktop  application 


Cojsyrlglst  (e)  19B6-97  by  Apple  Computer,  Inc. 
All  nights  Refefved 


source  rile  KEfJiJ.cc  ^  Menu  bar  ln«rcirg/dEletlng  /  veet^rlng 


llnclude  <types.h? 

•  Include  <iiifinu,li> 
( include  «lesfc.Ji> 
llnclude  <wlrniow,Ji5 
Unclude  <3nenicjry.h> 

♦  Include  <lntjrath.h> 
I  Include  <ftiisctoi!l .  ti> 
llncluda  <tei[tt:(H!il.h> 
tinclude  "fip.h" 

/'  Bunch  of  routines  defined  sometfhere  ol&e  •/ 

CKtem  DoCls-seltEmO  ; 

EK-tern  DoAboutltenijj  ; 

Extorn  DoQultrcemo  ,- 

extern  Doqaenltem  (> 

extern  DoSaveltEm  {)  ; 

OKtem  Docfiooeerlteir  () ; 

CMtem  DoSetUpItem  [)  ; 

extern  Dnprlntlteir  (}  ,- 

esrtorn  DoChan<jeHes  ()  ; 

extern  DoGpenltemo  ■ 

extern  DoSetMano () j 

estern  DosheirtFeri  ()  ; 

•Mtern  HftiTasltllBc  IheEvent; 
•xtem  GrafE-ortptr  WhJchWlndow; 
•Ktem  GrsfPortPtr  wlndoMLUt  [Ifi]  ; 
extern  int  windex; 

char  lDstr[S|  -  "\MJ300\r"; 
eittern  char  str  [  ]  ; 

/•  FJere  we  have  all  defines  for  all  the  menus  •/ 

char  'Menus  f]  -  { 

/•  Fonta  menu 

"»    font*  \\N6\r\ 

—Display  Font  . . . \V*FfW2Sfl\r\ 

-Display  Font  a,  «tono-spacad\\.MMf265\r.-v  /•  coirpUer  4dds  -O-  ,t  the  end 
/•  Windows  menu  •/ 

'»   hisdovf  \\mb\i\ 

—do  WIndokra  AllocatedS\NZS9\r.", 
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/•  tau  Menu 

"»   Edit  \\DK3\r\ 

— Ptste\\'VvM253\r\ 


/*  rile  Menu  */ 

■»    File  \\N2\r\ 

— o^n  ...S\»OciN25B\r\ 

-<lose\\D.'J255\r\ 

—Sive  As  . . ,\\DS259\r\ 

— V\?(2S6D\r\ 

-<hMse  PrlntBT. ,  .VWI60\r\ 
"fi^e  Setup  . , .\\DN261\r\ 
— frinc.  .  ..^^D'Ppl^^6^\^\ 

Apple  Manu  *  / 
"fttHJUt  Hodgepodge ..  .\\N25£^^^ 


I 

Dat«RecftT  dacef tefsp; 
lut  index,  1; 


HlilchMirLdow  -  FtontHlndaw  (> ; 

TuBipKandle  -  (DataRecHandlel  GecWRef  Con  (WhlchXindow) 


derEfcemp  -  "TenpHandls; 

IntZDacfNlndeii,  IDStr  +  3^,2,0); 
ID£cr[a]    I-  flit3D; 


LMeiL  -  (detEfLefnp  ->  Str[0]|  +  1; 
tor  (i-0;l  <-6;l++) 
denftenp  ->  Stxll  +  index]  -  IDstr[l); 


InwrtHItan (t  (dereftenp  ->  Blank) ,  Oxfrff,HlndciuaienulD}  f 

f  this  is  the  first  window  *f 


if  ( [ (Mlndex) ) 
I 

DelntcMItem  (2  99}  ; 

SecHenuFlag  (0Kff7f,viiiidowa!ferniID)  ; 

I 

CaicKenuS  Lze  (QL,Hindcw£KenulD} ; 
UlndnicLlstmindsii]  -  WhlchWindow; 

HUnlock (rempHandleJ ; 


/'  Token  Item  */ 
/*  highlight  the  menu 


DdnteroO 
i 

WhlchVfindow^lnjaawLlBt  [  (ThoEvflnt.HntTaskDatasnxfff  f]  -  300  ]; 
Do«lndo«(|; 

HI  1  It eHanu  (FJLLSE,  TljeEvent . vmTa sItDat  a/Oitf  f  f  f )  f 


MENU.CC  (menLis)  363 


( 


ease  OndolD 
ease  CutlD 
caa*  Copylfl 
easQ  PastalS) 
case  CiearlD 

case  About  ID 

cass  a-iitlD 

case  CpenWiD 

caca  SavelD 

casB  choose ID 

case  SfltUpID 

CaH  Print  ID 

case  ShowFontID 

MBS  HonoID 

case  295 
default 


:  hreaiti 
:  hieak; 
:  break; 
:  brealt; 
:  break ; 

:  tJocioseltemtJ; 

breaJcj 
:  DoAboutltemO  ; 
b^eafc,• 
:  DoQu  it  1 1  an  (in- 
break ; 

:  DoQpenltemO  ,■ 
break; 

!  DoSaveltem  (I  ; 
breait; 

:  DoChooserltem  {) ; 

break ; 
:  DosetUpltemO  ■ 

break; 
:  PoPrlfitltcm  0  ; 

breaJc; 
5  DoC^enlt^  (J  ; 

break; 
:  DgSetMonoO; 

break; 
:  btEak; 
:  .DoWItBfflO  ,- 


/*  w«  do  nothing  with 


/*  these  ! 


Dili  teMenu  (FALS      The  Event .  wmTa  sJtDa  t  a  /  Ox  E  f  f  r  f  ; 


SatUpMenus  () 
( 


int  Meniilooper; 
SetWlitleStart  (101  : 

/    Set  starting  pos  of  menus  •/ 

nT.lTr  '  f  ^  -A...  if  an,  V 

" '  ^    ""^a"  the  msnn  b.r  on  tije  screen  */ 
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EVENT.CC  (main  event  loop) 


UodgePodQ« ;     An  e^tample  Apple  IIGS  lltesli^Dp  app^LcaLinn 


CnpyrJght   (c)   1986-87  by  Apple  Cpnputer,  Inc. 
All  Sights  Reserved 


Source  file  EVENT.CC  —  Kaln  event  logp  arul  window  acclvatlon 


Include  <tYpe£,h> 
Ijiol  Ude  <jiieiiiory  .  Ji^ 

Include  5wlr<dox.n> 

Include  <prodos.h> 

iDGiude  <nit3ctt]ol-h> 

Icic  Lude  <text  tcq  1 .  h> 

Incl'jda  laiienu.h^ 

Include  "hp.h" 

altera  Int  _toolErr,' 
extam  PHina^f  Faund; 

int  OJltFlsg  -  Q; 
Crafi'drtptr  LastWlndtw  '  MIL, 
ThlsWindow  -  NIL; 

Int  Actlv»t*rlag; 


itruct.  HandleRec  { 

char  'ptrpart; 
Int  flags; 

1; 

/'  for  Open 

t^ndflf  struct  Opennec  I 
Herd  CpenRerNuni,- 
Ftr  openpachname; 
Handle  IDBuffef; 

)  OpenMc,  •OpEnREcPtr,  ■  •OperRecHndl; 

V 

OpenEoc  MyCpertPai-ams  -  [0,0,  OLl; 

/•  lor  Etsad,  Hrlte,  Close,  Flush 

typedef  struct  FllelOAec  ( 
Hord  flleRefMum; 
Ptr  dataBuElEr; 
Long Int    rflquestco  unt ; 
Longlnt  tranaferCount; 

1  rilElosec,  "FilelORecPtr,   "FllelORecHndl;  '/ 


EVENT.CC  Cmain  event  loop) 


3B5 


DL, 

OH; 

DL, 

0x80001, 

01.  i; 

FllelORec  CloneParams,- 

/*  for  Creace,  Setnialnfo,  GetFUelnfo 

typedef  fitfutit  FlleRec  { 


dataBuffer 
/*  raqueEtCount 
/*  transf erCounL 


/'  flleftafNuffl 
/*  dataBufler 

/*  requestCount 
/•  trsTsif  erCount 


•J 


/'  most  remains  unused  */ 


Per 

Word 

h'atd 

f  lleType; 

Longlnc 

auxType; 

HoEd 

st■ora3eTvpe; 

Hoed 

createDate; 

Hqrd 

cfeateTlnie; 

Herd 

modDate; 

Herd 

TtmdTijiie; 

Longlnt 

i  FlieBec, 

,  "nieflecPtr, 

fIIeRhc  CreateE«r«im»  -  ( 

01, 

OxOQc3, 
0x0006,, 
OL, 
1, 

0,6, 

OLl; 

/*  for  Destroy,  ChangePath,  ClearBi,c):upBl.t:,  GetPathfiaftie,  GetBootVol 

CVpedef  struct  FathNameRec  I 
Ptt  pathname; 
Ptr  nawPacluianE; 

)  ?atliN«]iieIlec,  *PathNa!iveaecPtr,  "PathHameflecHndl; 

PathNaflieRec  Dflstfarans  -  )DL,OL}; 

MBiTaBliHHCr  TheEvent; 

HainEvetit  1) 
I 

Int  MyEvent; 

TheEvetit.wmTaslLMasJt  -  DxOaoODfff;     f  Initialise  naiX  "/ 
do 

I 

do 

1 

ActlvateFlag  -  0; 
CheckFrontW  (1  ? 

llyEvent  -  TaskMaster  (DxFFFF,  »TtieEwent)f 

[ 

while (!  MyEvent)  ; 
switLcti  (MyEvBnt) 
1 


386 


Appendix  F:  Hodgepodge  Source  Code:  C 


esse    actlvateEvt  :  DoflctlTat*  (J  ; 

case  17:  in  menu  '/ 

DdMenu  I ) ; 
break; 

caea  ^5:  /•  In  joaway  •/ 

pocigaeltemi)  ; 

case  25;  /•  in  special  menu  Item  *y 

DoMenuO  ; 

i 

I 

I       while  {I  (OuUfla?) )  f 
I 

BoOuitlteoi  0 
I 

^    OultFlag  -  OxBOOO;  /*  aimpl*  uh!  '/ 

i*  Chsclt  If  the  front  wlndcw  ha*  ctisngad  ar.d  react  accordingly  '/ 

CtacliFrnntH{j 

t 

SataRficHardle  TmnpiDataHanql,; 
BatailecPtr  TeaipDataPtr,- 

Thl»Ml.[i(li™  -  FrontMlndoH  (J  ; 

if  ( I  (ThiBWLndoH  —  LaatWiraJowj  ) 

[ 

if  (LastWlndow  -  ThlsHlndoH)  /*  at  lease  one  window  •/ 

1 

ir  { I  (GetSysWFlag  (TlilfiWindow]  ) ) 

I 

SetLfpForflfipWO  ; 
If  (ftstiirateFlag! 

Tem^PataBand  -  (DataRecHandle)  GetMHefCon  (TheE«ant  .wtnTaskSata) ; 
else 

TampDataHand  -  (DataRecHandle) GatMRafConfThisWlndcw) ; 
TampOataPtr  -  •T^mpDataHand; 
KLack (Tempo at aKand) ; 
ll  (rampDataPtr  ->  Flag) 

Dlsablemtein  fSavalD)  ; 

EnableMItem    fSavelDj ; 
HUnlock I Tempo at a Hand)  ; 

1 

else 

SetUpForDawO  ; 

1 

alsa 

DlsableAll  (j; 

f 

I 

0«Ai!tltata() 
! 

if  (IheEvert -imModlfiers  t  1) 

\ 

fcctlvateFlag  -  If 


I 
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ChackFFontW  lij 

1 


I*  Disable  UemE  not  applicable  */ 

DlsablofLll  I) 

[ 

SetMenuFlag  (CJkOOBO  ,  EdltMenulDI  j  /*  disabla  */ 

DrauHenuBaF  {); 

DLsableltsms  (); 


SetUpFDCAppW  0 

I 

setHenuflag  {OxOaBIl,i:ditwnuIDi ; 

DraMMeciuBar  H  i 

Enable It ems  fl ; 


SetUpForDsWO 
\ 

DlBdt^leltemsO  : 

SEtKenuFlag  (Osir? I, EtlltlfellUID)  ; 

1 

Enableltems 
\ 

EnableMItani  (.^avelDj ; 
ErtableMItEHi,(CloBeHID|  f 

( 

Enabl€Htteii!(FiifitlD} ; 
EnablaMltm  jsetOpID)  ; 


/•  dcn't  aiublc  If  printing  *l 
/*  Is  out  of  tha  quest  ion  I  */ 


DlBableltans  C! 
1 

OlsataleHItem  (Save ID] ; 
DlsableKIteni  ICloseWID)  ,• 

DisableMlteni  (PrintlD)  ;  /*  who  cares'? 

DlsableKltera (setUplDj ; 

t 


/*  Kow  some  1/0  stuff,  tni*  file  Is  just  Olt  for  It  */ 

OFEI!  (IMyOpanParanfi)  ; 

If  t  tcmlErr) 
( 

CheckDisItError  (11  ; 

laturnlFM^E);  /♦  couldn't  open  »/ 

1 

( 

ReadFaraitia .  f i  leRefKum  -  t>lyDp«nFaraiti£,op6riReINUm; 
cln^ePdrdms.f ilBEtefNtin  -  HyOpenFarams .opanRefNmi,- 
READ (iBeadParams) ; 
if  (_toolErr) 

{ 

CUISE  UCloseParams} ; 
ChecJtDlsliError  (3)  f 
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return  (FAIiSE) ; 

]■ 

else 

( 

CM  SE(  5  Close  Pa  rams  J ; 
rttum  (TRLTEJ  ; 

1 

1 


ineOrte  () 
1 

Crests  Par  4C1S.  path  name  -  MyOpenParams  .(jpenPathnajBs; 
DMtParams , pathname  -  WyOpanEarams.  openPathname/ 
ClonParaniB.flleRefNuic  -  Ky{]peiiPsrams.operJile£Nuiii; 
treateParams.file'IypE  -  Oxcl; 
CrBateParams,aiiitType  -  0; 


EESTnaY  (*D«stEarams) ; 


I 


CREATE [(Create Fa rams) ; 
If  (  taalEtr) 
(  " 

CLOSE {tCloaeParamal ; 
cneckDliJcError  ( J} ; 

I 

( 

OPEN  HKyapsnfAiemsy ; 
it  (toolErrJ 

[ 

CLOSE  (tclosfiParams) ; 
ChacJtBisJcErrar  (4)  ; 

} 
( 

WrlteParama,  f  llERefNum  -  i^OpenParajna.opanBefNvmi; 
HRITE.(«HElteParairs)  ,- 
if  (_toolErrj 

[ 

CLOSE (scioseParams) ; 
Ch6ekDls!tError(51  ; 

} 

else 

CLOSE (tCloseFarams) ; 

I 


WINDOW.CC  (windows) 

'  Hodg^Fodge:    An  eptample  Apple  IIGS  Deslctop  application 


copyright  (cl  19B6-S7  by  Apple  Computer,  Inc. 
All  Ritjhts  Reserved 


•  source  rilE  windcH.CC  —  Window  opening  /  closing 

I Include  <type3.h> 

tlnciude  <qulcl:draw. h> 

(Include  <wlnciow,h> 

llnclude  <3tdflle.h> 

(Include  <pi:odoa.h> 

(Include  <»enioiy,h> 

(Include  <qdaux.h5 

(Include  <font.h> 

(Include  <ineiiu.h> 

llnclude  tdesk.h? 

(ijnislude  <jiitactool.li> 

(include  ^CExttQcl  .>i> 

(include  <inCniath.hs 

(include  "hp.h- 

extarn  GrafPortPtr  OxigPort; 

extern  char  str[l? 

/*  stuff  to  dEfine  the  window  data  structure,  defined  in  HP,H 
typedel  struct  DacaRec  { 

handle  PlcHand; 

char  Blank; 

char  stf [3D| ; 

char  mstuff[61f 

Byte  Flag; 

char  Extra; 

I  DataRec,  ^DataRecPtr,  • 'DataAecHandlf; 

*/ 

DataHecHafidle  MyDataHandie; 
DatflRecPtr  Refpcr; 

/•  This  structure  la  defined  in  window. h 
typedef  struct  WnlasfcRee  ( 

Word  wmWhat ; 

DblWord  wnMEB^ege; 

DblHord  MnWhen; 

Point  MnWhfire; 

Word  witWotllfiera; 

DblWord  wniTasliDaca; 

□blWoid  wmTas)tMask; 

I  f4iiiTasItnec,  *waTas)cRecPtr,  •*WhiTaaJtRecHndl;  V 

•xtflrn  lilluTa*]ci!ee  TheEvBnt; 
extern  char  *LlnftTable[] ; 
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tAetn  Int  tMlErr; 
extern  Int  MylD; 
eittem  Int  ThlSModa; 

Wtem  SetPutTanvplate  SPPS^OTempj  /•  tenplates  for  StdFile  */ 

eSar  flriflltemtl  ^  "—Mo  Windows  allocated\\BJS9\r";  /*  first  Item  In  wirdowa  */ 


BKtirTi  Int  HcnoFlag; 

ucetn  FontID  DeslradFont; 

txtam  int  EaintO; 

4KtBm  Int  DlEpFontWlndow  ()  ; 

pucil  int  opanFi  Iter  {)  ,- 


/*  see  Font.c 

/*  Hlndsw  cortent  proc  */ 
/*  Hindcv  def  Proc  for  fonts  ■/ 


/•  t^iedef  stn 
Integer 
HQrd 
per 
Innfl 
Rect 
?tr 

Integer 
integer 
Int agar 
Int agar 
Integer 
Integer 
Int agar 
Integer 
Integer 
Intager 
DbltteFd 
Intege:r 
Ptr 
Ptr 
Ptr 
R»cl 

WEortPtr 
wlndRecPt 
>  PtramLl 


uc^  ParamLifit  i 
paramLengthf 
MFrajneBlta; 
wTltle; 
wEuifCiin; 

wCalprr 
uTOrlgln; 
wXOrlgln,- 

wDataH; 

wsetoltver; 
KScrollHor; 
w&ageiVer; 
wFageKDr; 
wlnfoBefCon; 
wJnfoHeight; 
wFraneDe  £  PrDc; 
wlnfoDef Proe; 
yCnrl  Def  Proc; 
wPn^ition; 
wPlane; 
wSceragB/ 
St,  *Paraj!LLlstPtF, 


' ParimLlstHndl; 


Elieof InyHindoH) , 

i* 

Becoid  sixa  •/ 

DxddaO, 

/* 

Ftaffle      cLdaf)  •/ 

/' 

Ptr  to  title  */ 

01, 

/* 

HafCon  ►/ 

0,  D, D,  a. 

/• 

Full  Else  (0  -->  default  J'/ 

01, 

/« 

Color  Tibia  Etr  •/ 

0, 

/• 

Vortical  Origin  */ 

0, 

/* 

Horizontal  Ojrigin 

/* 

Cata  area  hlght  */ 

640, 

/• 

Data  area  uidth  */ 

200, 

/• 

Max  COM.  height  '/ 

£40, 

/- 

maK  cont  mldth  ■'f 

4. 

/- 

plKels  to  scroll  vert 

♦/ 

It, 

/• 

pixels  to  scroll  hort 

'/ 

40, 

/' 

pIkbIs  to  pagfi  vert 

'7 

ISO, 

/• 

pixels  to  page  horz 

V 

OIm 

/• 

Info  bar  string 

•/ 

0. 

/* 

Info  bar  height 

*/ 

01. 

def  proe  ptr 

«/ 

OL, 

y*  Into  bar  daif  proc  */ 

Piiftt, 

Content  def  proc 

'/ 

0,0,0,0, 

slie/pos  of  content 

-I 

-IL, 

/* 

plana  of  tfliido'w 

•/ 

01; 

/* 

Hiiisl  Rec  add 
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extern  rllalOftec  H^adp^rams; 
extern  FilelOAec  WrlceParans; 


Beet  ISlzPoe  -  {ia,ia,a(i,mn ; 


/* 

typedef  struct  FonclnfoRaGord  ( 
Lnteger         as cant; 
integer  descent,' 
integer  wldHax; 
Integer  leading; 

I  Fontlnf&ftocord,  ^Fa/itliifciRecPtr,  '*FontInfoIlecHndl; 

V 

FontlnfoHecord  FIDflcord; 
SfReplyBec  Kyaeply  -  [0,0,0,"  "|; 
■xtem  ppenBec  KyOpanlmiasss.; 


e^ar  Proenptl  []  -  "VpLoad  which  picluraj"; 
char  Prcxnpti  []  -  "\pSave  which  picture:"; 

Int  tfyorrset  -  12; 

handlH-  PicIUndle; 

extern  boplean  OpsnWlndow 1 1 ; 
extern  beelean  Kdko^erO; 
QKtexn  boolsan  LoadltUpf); 
sxtem  boolflan  DaTheOp^n  j)  ; 

Craf Forts  1 1  Wh  i  chWl ndow ; 

GrtfPortPtr  WindowLlst  [16)  I 

Iflt  VIndex; 

CrafPortPtr  vTabl«(161; 

Int  Winderx  -  (J; 


□penRBC  [ 
int  epenRefSwn; 
ptr  openPathname; 
Ion?  lOBuffec; 
J  •/ 


/»  handle  to  picture  data  */ 
to  add  window  to  menu  */ 


/'  current  window  hand la 

/'  list  of  window  handles 

/*  index  to:  | 
/'  W  V 

/*  liet  of  what  was  visible 

/•  index  to  next  avail  wind  id'/ 


Loclnft)  srclnfe«40 


oxeD, 

/*  UEed  to  be  byte  here  •/ 

OL, 

160, 

10,0,^00,640) 

1; 


R^ct  StcHecte^O        -  [0,  0,  200,  S4Q!  ,■ 


/'  Now  the  real  stuff 

/'  Procedure  to  Close  windowa,  we  close  them  from  the  back. 
Things  move  faster  this  way. 

V 
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I 

vindes  -  D;  /'  inlt  Index 

If  (vTabie  iirlndeKl  -  FrontMtndow  ( j  1  /*at  least  one  window 

! 

■ for  (vlnd&K,-vTable(ulT!at!ii  +  l\  ^  GetN&*tl#indo«(vral3le[vIndeKf  1  .'vlndex'r)  j 
for  (vlndex;¥ Index  >-  Qrwlndax — | 
HideWindow (vtable [vtndexj ) ; 

1 


/•  DoOpHfiltera; 

1)  Matte  EuxE  chac  there  aren't  too  many  windows  open  alreiadyi' 

2)  Cdll  OpenHind&H  to  let  ths  user  sse  it;  If  suc:ce3aful, 

3|  Call  AddtDMenki  to  adfl  the  nsme  to  thse  windows  menu  list. 

•/ 

KiDperlteir.  0 
1 

If  fWlndeK       NUM  WINDOWS) 
H3nyVflndDla,log  Of 

elae 

I If  (C^jiWindow  0) 
AddloNenu  |)  ; 


/'  Oper.Mlnaottj 

II  Caiia  SFGetFtle  to  get  ratne  of  file  to  display  in  wlndohi 

(□r  the  did  log  to  select  font  if  needed} 
2)  Gat*  memorv  lot,  and  loads  the  picture/font  data  Into  memory 
31  AliooatBs  a  new  window 

Ialpute  handle  ta  MyWindoHlnfo  in  WrefCon 
b)  note  that  wcontDefPtoo  Is  set  to  "Paint" 
C)   [or  fonts  wContDefFCQO  is  set  to  "QispFontHindoW 


r 


Ttifl  dafiniticn  of  (^fWlndowInfo  Is  global  data. 


ftpolesn  OpenVflndowO 
I 


I 


if  ( tTheEiTEnt-vonTasltData  e  Okffffi  --  ShowFonCIDl 
{ 

if  (DochooseFont  () ) 
if  (DoTheOpen   ()  | 

return  (TtlUEJ; 
else 

return  (FALSE) ; 

ei9e 

return  (FALSE) ; 

I 

tlsa 

I 

if  (AakasErO) 

return (TRUE); 
else 

return  (FALSE)  ,- 
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/• 

typeder  struct  SFReplyRec  [ 
Boolean  good; 
Word  fllerype; 
Word  auKFlleTypa; 
ctiar  fllenflSRe[lSJ; 
char         fullPathnair.eJl;?] ; 
1  SFRopJyRec,     •SFRBplyRecttE^  ; 

boolfran  AsJfLTsef  (1 

if  (iflidltUpf)  ) 

retujro  mu£)  ; 
elsa 

return (FftLSE) ; 

eLsE 

^  retucn, (FALSE) ; 

boolean  Lsad.It Dp  (J 

PlcHandle  -  NewHandlB (OxBOOOl, MylD,  0, Ol) ; 

If  (_toolErrl 

return  (FAUE) ; 
else 

I 

ileatlParams.ttjtaBuffar  -  •PicHandlB- 
HLoElc  (PlcHandlal  ; 
Ir  (DoTheOpanO  I 
return  {TRUE]  ,- 
else 

ret urn f FALSE) ; 

i 

twolean  PoTheOpano 

Int  aiU(l,aiix2; 
ptr  aux; 

boolean  lOError  -  FhiSE; 
Int  1; 

/'  thEi-e  la  always  a  ne-ed  •/ 

long  FlDAuji; 

My^taHandle  -  (P*taftecHandl,)N.«H,ndU(  (Ion,,  „l,,,f  f„,taR.c,  ) 
MyWlndp«.„Refc«n  .  (len^jMyDataH^ndle;        ^^^^  0«=°''<'. 

If  I_toalErjcJ 

return  tFALSE) ; 
else 

I 

RafPtr  -  'MyDataHandle; 
KLosk  IMyWlniHw.tfRBfCon)  ; 

The  ass^ptl.o  1*  t),at  th.  Wind™  1.  for  a  picture  ,nut  a  fcnt,  •/ 
^  /'  picture  flag  ■/ 
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1£  ( (TheEvent  .vtnTasltData  t  (JxffEft  —  StiowFontlD)     /•  were  ke  rigtits  »/ 
I 

RefPti'  -?  Flag  -  DJtX  I  MotinFLag;     /*      No  I  so  change  */ 
PlcHandla  -  {handle )    ( (DaslredFont.IamNi^i)  + 

(DeslredFont-fontStze    •  DxlOOOODDJ  + 
(DesiredFont.fDntStyla  *  OkIOOCOH; 

/*  eiierythlng  to  font  */ 

/■•  display  "i' 
MVHlndow.wCDntDefProc  =  (VoidErocPtr I  DlspFontWindow; 

I 

else 

Hyoper.Params.operit'attinama  -  Myftftply.  fullPachname; 

If  C  (LoddOtieO  )) 
lOError  -  TRUE; 

]  /•  Hsnd  of  picture  stuff 

If  (IO£rrorl 

i 

DlsposflHandle IMyWlndDw.wRefCon] ; 

DlspoaeHsndle  jPtuHandla) ; 
return (FALSE} ; 

J 

alee 

[ 

Hef?tr  ->  PicHand  -  PicHandlc; 
RefPtr  ->  Blank    -  0k20; 
KyHlndoH.wTltle  -  RefPtr  ->  Str? 

If  (1  {HyReply.flleiis!ne[t)l  <-  MajOJamesi  je) ) 

MyRepiy.fllenafneLO]  -  ManNaRieSl le; 
for  U-MyRaply.fllenanieEO]  ;1>-0;1"> 

ReiPtr  ->  str[l]  -  MyReply,fUeflajiie[J.]  ! 

MyHindow.uSataM  -  G4{}; 

MyHindow.wHaxW  -  54 D; 

ISlBpos.hZ  -  35a.- 

Hylflndow.HDataU  -  200;  /*  in  case  is  a  picture  */ 

SetPort^  {OrigPort)  ; 

if  ( (T^i^Evertc.wmTaelCPata  t  DxFFFF)  --  shOwFontlPl 

i 

riDAux  -  GetFontlD  [I  ; 

InstallFont (PlcHandle,  0) ; 

GetFontlnfo (tFlaecord) ; 

MyHindew,  t^DataK  - 

( (FIRecord. ascent  *  f'IRecord.dascanc)  >  (tiimLines  +  1)); 

FindHaxWidth  {)  ; 

Irsta llFont  IFIDAux, 0} r 

} 

windnwE  have  to  offset  evenly  */ 
HyHifidow.viPosltlQn.i/l  -  Wyoff Bet+ISliPffs.vl; 
MyMindow.viPosttlon.til  •  Wxoff set+ISliPos.hl; 
Hy  WltidoH.w  Posit  ion.  v2  -  Wyoff  set+ISltPoa.vir 
HyMiridow.viPofilcioti.hZ  -  Wjtoffuet+ISliPuB.hi; 

Kxoffset  +-  2Q,- 

if  [(MyoEfset  t-  12)  ?  izo) 
HyoffMt  -  12; 


WINDOW, CC  (windows) 


395 


HhlchMiirdow  -  NewHlndow  (sMyWlndcw} ; 
SetPort   (OrlgPort)  ,- 
HUnlOCk  (PlcHanilLijJ ; 
SotOriqiflMaslt  (OKFFf  E.WhlchHlndowl ; 
InltCursor  i)  ,- 

rettjtnfTHUEj ;  /*  final  ly!  '/ 

I 

I 

I 

void  QoSdvetcemO 
I 

DataElecNandle  AuxHandle; 
Pointer  AmcFtr; 
int  i; 

HtllchHlndbU  -  FrnntWlnijpw  ()  ; 

AuxHandJe  -  {DataRflcHandla)  GetWHef Con  (HnUhHlndEW) ; 

RafEtr  -  'fiuxHandle; 
HLOCk {AUMHandlet ; 


it  ([(EtafEtr  ->  Flag))  /'  save  only  type  0  windows 

I 

I4yC^nF«rana.op«nFathnanie  -  GetWTltlBfWJilchWindssw) ; 
SFPutFlle  (20,  2a,  PromptJ.HyOjwnParama.oponPathname,  IS,  iHyReply)  ; 
if  myHeply.gDcd)  /*  <;>  a  — >  OK  to  uve  It  */ 

I 

WaltCursor  ()  ; 

PieUandle  -  HefPtr  -i  PlcHand,- 
WrltePararna.datiBurfoj:  -  'PicHandJe; 
HLfjck  [PlcHandlel  ; 

Hyi:;»nFarajiui,epef)Pat]inane  -  MyReply.ruilPathrarae; 
SavaanaO;  /'  s^Ve  the  pletura  */ 

for  ti  -  MyBeply  .fllonanielO]  ;1  >-  0;  1 — J 

HefPtr  ->  strtU  -  MyReply. filename [il f 
EetMTltle  (HefPir  ->  Str,  WhlchWlndotil  ; 
Htlnlock  (PieHanilleJ ; 
CalcMenuSizfl  tQL,wl^dDW5Henul[>)  ; 
InitCunort) ; 

1 

1 

1 

Thl»  routlriE  finds  out  how  wide  the  window  should  be  for  the 
current  font 

•/ 

FlndMaKWidth(3 

i 

Int  tempFIa^s; 
int  LineCoiinter; 
int  aux; 
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tonpFlags  -  CetFotJtFlagsd 

SstFontFlaqa t (Sef ?tr  ->  flag  »  Ij  t  Ij; 

Cot  (LlneCounter  ■-  l?LlneCounter  <  WumLlnea,-Ll[iECoimter++) 

It  t  (flUK  -  Sti:lngWidtJi(Llner#l}le[LineCi3iinte[rl))  >  HyWlndou.yDataW) 
KyHlndiJw.wDataH  -  auut; 
HvWlndou'.wDataH  1.0; 

SEtFuntFlsgsltempriiffslf  /•  put  Il*q$  b4CH  •/ 


/•  close  a  ulnduv)  snd  dispose  uf  esttra-d^ta  (In  wSefCcri) 
and  reniave  it  from  window  list 

V 

I 

EUtsRecHandlE  tenpKandZ; 


itt  IDDeUte; 
Itit  Cauntar; 
Int  IDStart; 


If  (WhlchHirdo"'  -  Front «lnd!)«(n 
I 

ClaseNDAByWlnPtr  lnnvlchWindowf ;  /*  If  it's  a  eya  wind  this  la  ST^su^h'/ 
It    i  t-ooi^tll  y*  eTrg?-  ir.Eans  wasn't  a  systeJn  tflrtdoirf 

[  ~ 

tampHandS  -  {DatanecHandlel  SetNHafCo-n  tHhlcbVfindcyw) ; 
tanipPtr2  -  *teir,pHarid2;  /•  daref  */ 

ULoclc  (tempHand^) ;  /*  and  lock  It  */ 

PicKandle  -  tanpPtr!  ->  FlcHand;  /*  handle  to  yet  tld  ot'/ 


if  (tempFtr2  ->  Flaijl 
BlcKandle  -  NIL; 

if  (Wlndax  —  U 


-0  — >    font  */ 

/•  so,  don't  dispose  */ 
/•  taKHS  it  out  of  list  •/ 

/■  ore  wind  Is  special  case  *f 


InsErtMIceiti  (orlfllteni,0,WlndowsMsnuID)  ?  /*  no  windows,  message*/ 
SetHenuFlarji  (OjiOOBOjWlndowaKer.uID)  ;  /*  disable  windows  */ 

DraviManu&ar  () ; 


wxDffset 
wyof f set 


20; 


Delet^ItetndDDelBtel ; 
HlndoK — ; 


/»  reset  start 

i"  for  window  sizing  •/ 

off  the  menu  */ 


If  (Counter  -  Hindex) 


IDS  tart  -  3CH3,- 
IDHbw  -  300; 


/*  HtartlnB  paint  '/ 


while  (Counter) 
1 

if  (IDStart 


IDDeletfl) 


SetMItemID  (IDNew,  lEStarc)  ; 
Counter — ; 


iDStart++i 
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Calcliteniislze  (OL,Hlncigvi£MenurD)  ■ 
If  (FlcHandU) 
DlsposeKandlelPicHandle) • 
^  CIoseWindoHiwiilchWitidotfK- 

J 

i 

I 

int  ID€ounter,l,y,- 

1  -  Hirdeu  -i; 
IDCoufiter  -  I; 

y  -  1; 

whUa  C  ly  —  IDCsunEerl  | 

»lnd!)wLiflt[yl  -  l*iiidoiiLlst  [  v  +  u- 

i 

rettirnd)  • 

J 

•/ 

Paint  0 
I 

DaCifiEcfJandle  auKKandlej 
CiacaRecpti-  Ditaptr,- 
auxetr  -  Get  Port  ()  ■ 

EataPtr  -  "auxHandle;  •^""^lefc™  {au*Ptr| ;  ^.  ^anaie  to  data  V 

HIac!:  (auxHandle) ; 

P.i.tIMO«..tr-.  PI.,,,,,, 

HCJnlosk       Handle)  ; 


Palntlt  (PaJnthaiMS) 
handle  PalnthaFicl/ 


»UKPtr2  -  *ealntliard; 


Appendix  R  HodgsPodge  Source  Code:  C 


HLock  (Faint hand)  ; 

SiclnfoSlC.ptrToPljiWiafle  -  auxPtrZ; 
PPToPort  (sjrclnfoew,  tSrcFLecC  S40,  l>,  0,0) ; 
HUnlock (Paint hand); 

t 

EaGailway  ( ) 

: 

HldeHlndDH  (TheEvent .  wnTaslcData)  ; 

J 


s 

I 


SDcwWindsw  (WhichWindoH)  ; 


pasesl  Int  OpenFllter  (DlrEntxy) 
ECr  DlrEntry; 

/*  nitei-  function  callod  by  the  standard  FiLe  Operations'  SFtJetFLle 
dialog  to  detemlna  whethar  a  Illenatne  should  be  dlmred  or  not.  */ 

i 

IC  (('(DlrEntly  +  (JulO)  i  OxOOETJ  —  OxCl)     /•  Type  Kl:  picture  file 
rat  urn  (J);  /*  ...  so  IfB  undljiuied. 

■lee 

retUfrt  11);  /•  Else  show  It  dlmned.  */ 
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DIALOG.CC  (dialog  boxes) 


HodgEPodgo :    An  example  Apple  IIGS  Desktop  sppllcatio-n 


Copyright  (c)  1996-87  by  Apple  Computer,  Inc. 
All  Hlghta  Reeetved 


Source  fjle  DIAlflG.ce  —  Dialogs  and  error  trapplr^ 


tinclude 
Uncjyde 
♦  Ir.clude 
tlnclude 
i Include 
(ineludB 
'include 
tlnclude 
t Include 
* include 
•Include 
(Include 
(include 


<typeH.  H> 
iquickdraw.  Ii> 

<tneraory,h> 

<dlalog,)v> 

<prodoB. h> 

<;teKttool,h> 

<stdflle.h? 

<wlndoi«r.  ii> 

<locatnr,h> 

<lntjnath.h> 

<liilseiool.h> 


■xt«rn  Int 

Ejstorn  int 

extern  GialPortPtr 


tooJErr; 
MylD; 
OrigPort; 


GrafPortPtr 


MsgwlndPtr; 


/■  Data  atmcture  for  -flljout  HodgePodg* , . . '  dUlog  box:  •/ 

static  char  OKStf  []  -  "S,pqi;"; 

•^^^^  DRect  -  (20,15(3,193,450),* 

Afif^lelconEiect  -  i  135,       0,  0  J  ; 
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Chai  ftpplelconSIO  [  1  -  (0x00,  OkOC,  0*00,  OjtOO,Oi!2J,  DuOO^Qufl [J,  0*00, 

0*DD,DxDO,  DuOOfCxCIO.CStCCl,  0x00,  DxOO,  DkOO,OxOD,CrOO,  OkOO,  0x00,  0x00,  0x00,0x00, find 0, 
9j(Dr,Dxf f ,  DKff,  Oxf  f ,  Dxf f ,  Oxff ,  Oxf r,  Dxf f ,  Oxff ,  Oxf r,Clstir,Oxff ,  Oxf r,  Oxff ,  Oxf E,  D;if a, 
(Mf , 0x03 ,  OxCO,  OxO«,  0x00, 0x00 ,  0x00,  QxM ,  0x00 ,  OxOQ,  0x00, OkOP,  0x00,  OxSC ,  OxDQ ,  Oxf 0, 

Ditor, ojtof,  Oxff,  Oxf  r.o.tfj',  Oxff,  Oxf  f,oitrr,  Oxff,  Oxff,  oxf  f,oxff,i;Kff,  oxff,  oxfo,ojtfo, 

OxOf.axOf, Oxff, Oxf  E.Oxtr,  Oxff,  Oxf  t.Oxff, Oxff, Oxff,  Ox£a,0xBf,  0)(f  f.Cxff  .OxfO.OxID, 
OxOf ,  CxOf ,  Ox  f  f .  OKf  f ,  Oxff,  Oxff,  oxff,  Oxf  t,  Oxf  f ,  Oxi  B,  OxBB,  OxBf ,  Oxff,  Dxf  f ,  CxtO,  Oxf  0, 
mt,  OxOf ,  Oxf  f ,  [))if  £ ,  Dxf  f ,  Oxf  f ,  Dxf  £,  Oxf  f,  Oxf  f,  Ditaa,  CxSa,  OxEf ,  Ox£  f ,  Oxf  f ,  Dxf  D,  Oxf  0, 
OM£,DxO£,  Oxf  f,  Oxf  £,  Dx££,  Oxf  f ,  Oxf  £,  Oxf  t,  0xf8,  OxBB,  DxSS.OxEf ,  ax£C,  Oxff,  OxfO,  DxfO, 
fliOf  ,OxOf ,  oxff,  Oxf  f,  Oxff,  <J«f£,  Cxf  f ,  Oxff,  OxBa,  OxBS,  DxBB.oxff  ,Ixff ,  Guff,  OxfO.  OxfO, 

OBDffOxCf  fOxf  r,  flxf  f  ,oxff ,  Dxrr,  cxfr,oxf  f  ,0x88,  oxsa,  oxBf,  oxf  r,oxff,CKrr,oxf3,oxf  o, 

BjtOf.CxISf  ,!!xf  £,  oxf  f, Oxff,  Oxff,  Dx£f,Cxff, 0x88,0x88,  Oxff,  Oxff,  Oxff , Oxf  £,axfD, Oxf  0, 
DxOf,OxD£,  Dxff,  Oxff,  Oxf  B,  0*88,  OxSf,  Oxff, 0x38, Oxff ,  OxBa,  0x98 ,  Oxf  f,  Dxf  f  ,CxfO,  Dxtfl, 
DxGf,OKOf,Dx££,  Dxf 8,  0x88,  0x88,  0x88,  Oxflf,  0x11,0x89,0x08, OxBB,  0x81,  Dxf  r,DxfO,  OxfO, 
Q*0r,OxOf,Oxff,  DxBfi, OxBB, OxBB, OxBS, 0x88,0x88, 0x88, 0x68,0X88, OxSB, OxBf, DxfO, OxfO, 
tmOf , OxOf , Oxf e, Oxee, Oxee, Dxeo, Oxfie, Oxee, Oxco, Oxee, Dxee, Oxee, Oxe  f,  Oxff , OxEO , Ox£0, 
(!xO£,OxOf,C«£e,  Oxe@,Oxe«,  Oxee,  Dxeo,  Oxee,  Oxee,  Oxoo,  Oxee, Oxee,  Oxff,  Oxfi ,  Oxf !>,  Oxf D, 
OltOf ,  QxOE,  Oxf  e,  Oxee,  Oxee ,  Oxee,  Dxee,  Oxao,  Oxee,  Oxee,  Oxee,  Oxef,  Dxf  f ,  Oxff,  OxID,  OxfO, 
DxDf,  0x01,  Dxf  S,  0x5« ,  0x66,  Ox6fi,  0x66,  0x66,  0x66,  Dxfi6,  0x66,  OxSt,  Oxff,  Oxff,  OxfO,  OxfO, 
DxOf  ,OxOf ,  Oxf  S,  0x66,0x66,  0x65,  0x66,  0x65,  0x66,  0x66,  0x66, OxSf, Oxf  f,  Oxff,  DxfO,  OxfO, 
CHtOi,0xOf  ,Oxf  6,  0x66,0x66, 0x46,0*66, 0x66, 0x66,  0x6S,  0x6€,0x6£,Oxf  f,  Oxf  f, OxfO,  OxfO, 
(Mf,0xDI,Cxf4,  0K44,0xii1,  DX44,  0x44, 0x44,0x44,0x14,  0x44,  Dxfl4,  Oxff,  Ox££, OxfO, Oxf  D, 
OiOf,  OxOf,  Dxf4, 0x44, 0x44,  0x44,  DK«4,  0x44, 0x44, 0x44,  0x44,  0x44,  Ox5f,  Oxff, OxfO, OxfO, 
OxDf,  OxOf,Oxff,  0x44,  0x44,  0x44,  0x44,  0x44,  Dxit4, 0x44, 0x44, 0x4<,  0x44,  OxiSffOxfO,  OxfO, 
ClxOf,OxOf,Ox£f,  0x55,0x55-,  0x53,  Qx5&,  0x55,  DxSS,  0x55, 0x55, 0x5^, 0x55,  Ox5£,  OxfO,  OxfO, 
ax0t,0xO£,0xf[,  0x55, 0x55, OxSS-, 0x55,  0x55,  0x55,  0x55,  0x55,0x55,  0x55,  OxSf,  OxfO, OxfO, 
0)tOf  ,OKDf ,  Oxff,  OxfS,  0x55,  0x55,  0x55,  0x55, 0x55 ,  0x55,  0x5  5 ,  0x55,  Dx55,  Oxf  f ,  OxED,  OxfO, 
OxOf ,  OxOf ,  OxfE,  Oxf  1 ,  0x11,  0x11,  Dxll,  0x11 ,  0x11 ,  0x11,  0x11 ,  DxU,  0x11,  OxE  f ,  Oxf  0,  OxfO, 
Dxaf,OxOf,Oxff,  Oxff,  0x11,0x11,  0x11,  0x11, 0x11,  0x11,  0x11, 0x11,  0x1  £,  Oxff.  OxfO,  OxfO, 
OxOf, OxOf, Oxf  f,0*r£,Oxfl, 0x11,  0x1 1,  0x1  f,  Oxff,  0x11,0x11,0x11,  Oxf  £,  Oxf  f.  OxfO,  OxfO, 
OxOf  ,0xBr,OxI£,0x£f  ,0x17,0x11,  0x11,  Oxff,  Dxf  f ,  Oxf  1,  0x11,  fl'XlF,Oxff , Oxf  £,0x10,  OxfO, 
OxOf , OxOf ,  Dxf i, Oxff, Oxff,  Oxff,  Dxrr,OK£f ,0x f t,  Oxf  £,  Oxf  f, Oxff ,  Oxff, Cxff, OxfO, OxfO, 
OxCf,  0x00, 0x00,0x00,0x00, OxOD, 0x00,0x00,0x00,0x00, 0x00, 0x00, 0x00,0x00,0x00, OxfO, 
OxDf , Oxff ,  Oxf  f,  Oxff,  Oxff,  Oxff,  Oxff,  Ox£(, Oxff , Oxff,  Oxf  f, oxf  f,  Oxff,  Dx££,  Oxff ,  OxfO, 
flxOO  ,0x00, 0x00, 0x00, 0x00,0x00, 0x00, 0x00,0x00, 0x0 0, 0x0 0,0x00, 0x00, 0x00, 0x00,0x00 

Meet  rextlRBCt  -  |  IZ,  4, 200, 25  61; 

/•  Thla  Is  LCNGSTATTEJCTI-ftumsttEd  type  text:  -f 
chir  Textl  [1  -  "\1JU\0\ 
\1B\C10\0\ 
HcHlffePDdge  in  C\ 

\i\ 

\T\ 

\is\<i\o\ 

n  putpuorrl  nf  routines  thit  demonstrates  many  ^ 
features  of  the  Apple  I1G5  tgijls.V 

\f\ 

By  clie  Apple  TIGS  DevclDpnient  Te^S 

\t\ 
\t\ 

Copyrlijht  Apple  Computaz,  Inc.,  1986-1987, \ 
\r\ 

nil  riohta  reEBTvadV 
\r\ 

if4.0     October  ISal"; 


ilKt  ButtonBwC.      (1S3, 180,0, 0}; 


DtALOG.CC  (dialog  boxes) 
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/'  Dialog  TeniplatB  data  structure  lor  "Please  wait  while  ..."  dialog!  •/ 

char  PlsWtMsg  []  -  -Npplease  wait  wjillfl  we  set  things  up.,",- 

ItemTemplatB  Plswtltam  -  |1349, 

19,70,200,  640, 
9 tat Text, 
PlsHtHsg, 

0, 

NULL]; 

DlalogTarpUte  PlsWtlarp  -  ( 30, 120,  90,  5ZD, 

true, 
NULL, 

SPlaWtlt™, 
HULL); 


/•  Jllert  Tenplato  data  Btructure  for  too  many  windows  and  disi:  Error  alerts: 

ItemleiBplate  ouwiertlteml  -  (1, 

25,320,0,0, 

buttonlteu, 

OKstr, 

0, 

0, 

NULL}; 

IteraT«mplata  0ar|HettItBni2  -  (1349, 

11,72,200,  640, 
Stat Text, 

/•  ItenDBScr  —  will  fill  It  In 

0, 

NtJLl  ( ; 

AlartTaiapl»t»  OurAlertretji  -  [3D,  120,  SO,  Szt], 

0x80, 0*80, 0x80, axBO, 
(OtirAlertltaiil, 
tOU|-fllertIi:Eni2, 
JflULLff 


Che okroul Error  (Wliare) 


/•  ChaeHroolError  checks  to  saa  if  th.  laat  tool  call  completed  successfully. 
I  it  Just  returns.     If  net,  we  crash  using  th.  System  D*ath 

tiandler  (bouncing  apple> ,  -/ 


Int  H}iBr«f 


static  char  Deatf«sg  t]  ~  •\p  At  SJHOtXf  Could  not  handle  error 
Int  ToolErtQrSave; 
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Appendix  F:  HodgePodgo  Soufce  Code;  C 


TocslErrorSava  -  _toci].Eri"; 
ir  {TflfllErrorSave! 

{ 

Irt2Heii        (WhfirejTlEathftsg  +  6,4>; 
SysrallMgr  (TQaiErEorSavejDeathMsgl  ; 

) 


boolean  ChecknlsttError  [wnere) 

/*  This  routine  ctiEcJo  if  the  last  ProDOS  operatlan  caused  an  error.    If  so, 
then  we  change  Che  eurBar  tc  ttie  arrow  cursor,  put  up  a  Etnp  alert  dialog 
box  with  the  tejit  of  the  error  message,  which  then  wslts  fgr  the  user's 
OK  cllok,  ahd  then  ■ctisng'e  the  cursor  back  to  the  wrlstwatch.    If  thcr* 
was  no  disit  error,  then  we  do  nothing.    Mb  also  retLuxn  TRUE  or  FALSE 
depending  or.  whether  an  error  actually  occurred  or  hot,  */ 

Int  H?i»re,' 
t 

Int  DlskErrNuin; 

DlEliErrNuiii  -  jcooiErrj  /•  save  thla,  first  */ 

it  raiskErrtfumJ 

( 

OurAlertlteml.ltemDescr  -  'VpDlsl:  Error  sxxxx  occurred  at  SXXXX."? 
IFkt^Hex  {DlskCrrNuir,  /*  Put  ASCII  •/ 

OurAiartltemj, LtemDoacr  +  13, 

<1; 

IntJHen  (Whera,  /•  put  ASCII  */ 

OurAl*rllteM.ltemDe*cr  +  31, 
<1; 

Inltcursor  (),-  Sot  arrow  curBor  '/ 

StopMert     i»OurAlertTeiTip,NULL) ;  /»  Draw  dialog  6  wait  */ 

/'  Do  not  reatore  watch  cursor  ►/ 

1 

return  (DlafeErrNum) ;  Assign  function  result  •/ 


HinyHindDlalcg  0 

/•  Displays  cauEion  alert  dialog  with  a  mesaa^E  about  no  mora  windows 
baln^  allowed  open.    Handles  mouse  events  until  OK  button  is  cllcJcad. 
Than  the  dialog  boa  is  removed  and  we  return,  '/ 

1 

OurAlortltemz.ltemDescr  -  "\pNo  more  windows,  please.";      /*  sot  string 
^    CautlonAlert     (iOurAlercTemp, NULL) ;  /*  Do  draw,  wilt,  undraw,  ■/ 


I 


OoAboutltwn  () 

/'  Function  DoAljoutltem  shows  how  to  build  a  dialog  boK  manually.  */ 


i 


handle  ApplelconH; 
GraffortPtr  Mlalo^iPtr; 

ApplalconH  -  NewHandle  (552L,BytD,(l,0L) Allocate  memory  •/ 

ChBckToolError                (50);  Hope  U  was  ok  '/ 

Wl^ck                              (ApplelconH);  /'  Freeze  handle 

ftrloHand         (AE^leIcon640, ApplElconfl,552Ll ;  /*  Move  icon  Image  */ 
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Mdlilogptr  -  NE«ModalPtilog  (tDRect, TSt/E, 01(  ;      /■  Draw  dialog  bos 

Install  and  icaw  items  In  the  dialog  box!  •/ 
NewDlten,  [Mdlal  oqf tr,  l ,  tSuttonflc^ t ,  buttonltem, OKSt r,  0, 0,  rjLIl  • 

AppleIccifiH,0,  0,  BL)  ; 
NewDltM,  iMdialocjPtr,fl,(TeitURect,lonqStatTeKt!+ltemDlsable,™xtl, 


ModalDlalog  (NULL); 
CloeeDlalog      iMdlalogPt t) ; 
DlfiposaHandle  (ApplelconH) ; 


/'  Track  the  mouse  Inside  the  box 
Semove  the  box  frajs  the  screen 
/*  DeallocaLS  memory  ■/ 


/'  JhouPleaseWalt  /  HidePleateWait  •/ 

/■  Bfinijs  up  a  wlndov  and  puts  a  message  or  It 
witout  waiting  for  Update  Event  */ 

ShowPleaseWait  (J 
I 

OrigEiart      -  Get  Port  {}; 

MsgHindPtr  -  GotNewKodalDUlog  ((PlsMtTemp)  * 

DfawDlalog     [MsqWlRdPtri  \  '  "f^"*  Process 

^     EndUpdate  (HasWlnaptrl; 


HldePleaseWalt  () 

[ 

CioseDialcg [MsgWlndPtr) ; 
Sot Port  jarlgPort) ; 

1 


Mount  BootDlsk  [) 


!•  MountBootDisI:  is  (tailed  whenever  tha  application  requires 
something  from  the  boot  volume  and  It  is  not  online 


\ 


static  char  Prompt  Etr  [| 

OKScr  [] 

CancelScr  [] 

Volstr  [2561; 

static  PathNamseLec  CBVParaiM 


■\pPleaae  Insert  the  disk", 
"\psfiut  Down", 
1  VolStr,  NtJLx  j  f 


GET_BO0T_VOL  (tGavParatns)  ; 

return  (TLMou^tVoli^e  PiomptStr,Voistr,  □Ktr,CanpelStr| } ; 
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Appendix  F:  Hodgepodge  Source  Cod©:  C 


FONT.CC  (fonts) 


•  HodijePodga:    An  enimplH  Apple  liGS  DeaJucp  appHcatlo 


Copyright  !c)  1986-81  1^  Apple  computer.  Inc. 
All  nights  Raserved 


'     Source  file  FONT.CC  —  Choosing  font,  font  window  deEpro 

llnelude  <typea.h> 
llnelude  «qjici(draw.ti> 
(IfieiudB  <fOEit.h> 
*LncJu(Je  tflntmath.hs 
fin«lude  <fltilflie.h> 
itfielude  <tfin!jow.h> 
llncladE  <mamory,h> 
Unclude  <menu,h> 
HncJu<ie  <tejictool.h> 
(Includ*  -hp.fi" 

Mttm  SFPeplyftee  MyHeply; 
/■ 

typedaf  struct  SFReplyRac  j 
Boolean  good; 
Mord  file-Type; 
Word  ■uKFllerype; 
char         f  ilana[m  [161; 
char         fullPathnametlz^l  ; 
\  SFHeplyRec,     'SFREplyRftcPtf  } 


•Ktern  Int  _toolErr; 
t»tr  FontWinPtr; 

typsdef  struct  FuntlD  | 
Word  famNum; 
Byte  fontscylft; 
Byte  fontSlie; 

I  FontlD,   •FontlDPtr,  ••FontlDHndl; 

V 

rontlD  DeBirsdFont  -  {  Oitfffe,  00,OxOe|  ? 

Int  HonsFiag  -  0; 

/' 

typetteE  atruet  FontlnfoRecord  { 
intBger  ascent; 
intflger  desoent; 
Integer  HiijKa!i; 
Intesier  leading; 


1  FontlnfoHecord,  'FnnLlntQRecPcr,  *' FontlnfoRecHndl; 

•/ 

FontlnfoRecord  CurrFont; 
Int  CurrMflight,  Llnecounter; 
/' 

tjfpedef  struct  Point  I 

Integer  fi; 
)   Point,   'PointPtr,  **PolnE.Hndl.f 

*/ 


Point  CurrPos; 


char  ilrwD  [301  -  ( 0,  Oj  0,0,  0,  Cf,  0,  0,0,  0, 0, 0,  0, 0,  0,     /*      Natnelength  +  1  •/ 
O,0,0,O,0,O,0,0,0,Q,O,0,D,£l,D);  /•  +  4  for  alie  info  '/ 
char  Lineltl  -  -\0«; 

char  Liisei  [ )  -  "XpThE  quici!  brown  fux  jumps  ev«r  the  laiy  dog,  "; 
char  Llne3[l  -  "\pShe  sells  sea  shells  doMn  by  the  s^a  share, "r 
char  Llne4n  -  "VO"; 

char  Lines []  -  (32, 

D,  1,   2,  3,   1,  5,   6,  7,  8,   9, 10,11,12, 13,  H, 15, 
16, 17, IB, 19, 20, 21, 22,? J, J4,2S,Z5, 27, 28,28,30,31,01 I 

char  Lines [ ]  -  (32, 

32, 33,  34, 3 5, 36, 37, 3S, 39, 4a,  41,* J, ^3,<(, 45, 16,17, 
IB,  49,  50,  51,  52,53, 54,55, 5  6, 57,5B,5S, 60, 61,62,  63, Oil 

char  Llno7[]  -  {32, 

65, 66,  67,  68,59,70,71,72,73,71,15,76,77,78,7  9, 
BO, ai, 83,83,94,85, 86, 87, 18,89,90,91,  92, 93, 94,  35,  es- 
char Lines [1  -  (32, 

9S,   97,  98,  99,100,101,105,103,104,405,106,107,108,105,110,111, 
112,113,114,115,116^117,118,119,120,121,122,123,124,125,12  6,137, 

char  Lines  []  -  {32, 

128,129,130,131,132,133,131,135,136,137, 11B,13S, 140, 141, 112, 143, 
111,  145,14  6,117,  148,  14  9,  150,151,152,153,  154,155,156,157,158,159, 

0}; 

char  LlnelOIl-  <3z, 

160, 161, 162, 163, 1*4,165, 168, 167, 169, 169,170,171,172,173,174,175, 
n6,177,17a,179,IBD,ia2,ll2,lS3,lS4,lBB,lB6,  JB7,iea,189,190,191, 
0); 

char  lJn*ll  [J  -  (32, 

192,193,191,195,196,137,199,199,  200,201,232,233,  201,205,206,207, 

208,209,210,211,312,213,214,215,215,217,218,219,220,221,222,223, 
01; 

Char  LinBl2[]-  (32, 

224, 225,  22 6,  227 , 228,229,  230, 231, 232, 233, 234, 235, ?36, 237, 238,  239, 
240,  241,  24 2,  ?43, 24 4, 245, 216,  247,  218,  249,  250,251,  252,253,254,  253, 
01; 

char  'LinErablBLl  -  tLineO,Llnel , Line2,  LlnaS, LirLe4,llne5 ,  Llne6, Lirfl7, 
LlneB,  Llne9,LinalD, Linell, Llnel21; 

char  ProKsq[3  21  -  "--Dtfipisy  Font  as  Pr!^rtional\.r",- 
char  MonoMsg[31]-  "--Display  Font  as  Hono-spacedNr"; 
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Appendix  F:  Hodgepodge  Source  Code:  C 


'i 

int  kfP.Qcares; 


SrifPortPcr  oldPort; 

Ijit  teiiipPort[95I;  /»  port  slie  In  tytee  /  2  *■/ 

typedef  struct  FontID  [ 
Ward  fajSlKiJftl; 
Byte  fontstyle; 
Byte  (ontSlie? 
I  FontID,  *FDrLtIDPcr,  ••FontlOHndl,- 

•/ 

lofia  tempFont; 

oldfort  -  GetPorc  (>  f 
OpenPort  (teiuppqrt) ; 

if  [tempFont  -  ChooseFont (Desl red Font, 0) }  /•  font  changed  */ 

DoalredFont.faniNuii!  -  (WordHtempFonc  I  Oaff ff ) ; 
Pe3lredF0nt.fontSt.yl0  -  (Byte)  ( (tempFont        16  i  t  axfifi 
DeslrodFont.fpntSiKa  -  (Byte)  (eampPont  »  2ii  ; 
whocAres  -  GetFamlnfofDesiriedFont.famNum, 

HyReply.rllename);/'  Iflnore  fasult  •/ 
IntI[>Bc(D6slfedFont.foRtSiie,        /♦  siie  of  font 

1  (MyReply.fll6naiiiej  +  lMyliepiy,fnen4m«[01)+l)  position*/ 

/*  length  of  reault  '/ 
0)f  /*  not  sirred 

i^H6Sily.ril«naiM[ai   +-4;  /*  n,t,  legth  ■/ 

CloMfort  (tanpPortJ  f 
setPort (oldPoitj ; 

^  return  [TRUEt  f  /,         .^uff  -f 

else 
I 

ClosePort  (tampPort)  ; 
SetPort (oldfortl ; 

return  (FALSE};  ft  jlo  ching*  ■/ 

t 

mapFontWindOH  I) 


I 


mtm  fontld;  /*  oont  naed  it  '/ 

FDitallECHandle  Fofltfland; 
FUataRecPtr  FbntPtr; 

CnfPortPtr  tonpport; 

tmpPort  -  GgtPortO?  /»         curr  port  •/ 

FontHand  -  (f DatsHeckandle}  GatWfiefcor  (teanpPort.) ;  /*  get  handle  to  data 
FoniPfcr  -  ■'FontHand;  y.  derefeianca  '/ 

HLock  (FontHand}  ; 

ShowFont (FontPtT  ->  f ID, FontPtrJ ; 
JtUnlon)<  (FontHand)  ; 

1 

Bhatfflont  (fontid^FontPtr) 

rone ID  font Id; 
FDitallacPtr  FontPtr; 


I 
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{ 

■Old  tanpPlag?; 


InstallFant  (fontia,  0)  ; 
Getrontlnro (ICurrFonc) ; 

CurrHeigtit  -  currFont.aaoent  +  CurrFci;t.d««e«jit  +  CuriFont- loading- 


6«CFknln£a{fe)iitl4.bilHUVl>lM0}  r 
IntSlMo  (lontXd.  f ontSiHi 

(Lln«0)+lli»Otfl]+l, 

A, 

0); 


/»  bLw*  «£  toot  •/ 

/*  Iiin^cit  of  iwimlt 
/*  not  sioitwi 


eiM;Faiitn»g«({{{Pijireftr  ->  Flag} I  »  I)  *  l|; 


toe  [LliwCounter  -  OfUneCounter  <  llItiiiI,JU»*;l,in«Da«itM*+) 
C«tEen(tCurrPofij ; 

iWVaTolbjCiucrHfllaht  +  CurrPos.v)  f  /•  raMt  X  aoA 

St£Politn»§»{t«l¥Fl*g«) ; 

J 


) 
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Appendh  R  Hodgepodge  Source  Code;  C 


PRINT.CC  (printing) 


aodgaPoifge:     An  example  Apple  I  ICS  Desktop  application 


Copyright  (c)  1986-87  hy  Apple  Computer,  Inc. 
All  Rights  Hesecved 


Source  file  PBINT, CC  --  Pr!r.:;lng  stuff 

■» 


Ai4..|>Alt«l»#fl  nit9*frfi«fifrA  h -m  T  *  ■ 

flneluflE  <type9.h> 
iinclude  <]risjiiory.h> 
llnclude  <qulckdraH,h> 
^Include  fwlndow.h^ 
llnclude  <pFint,h> 
tlncluda  <qdaux.ti>> 
(IneluaE  cfont.h> 
llnclude  "hp.Ji" 

MttBrn  Int  My  ID; 

SMfPortPtf  HlndowToPrlnt  -  KIL; 
iiandlE  PrlntRecord  -  MIL; 
ErifPortPtr  PrlntPortf 
/'  Coosa  Erlnter  Item  hardier  '/ 
DoChaoserltera  [t 

I 

/*  Rojein«  tp  handle  pig*  catup  Item  */ 
DosetDplteni  0 

r 

If  (! {PrlntRecord) i 

setUpOe fault  0 ; 
Pr^tlDlalog  (ErlntRacordl ; 

r 

/•  routin*  to  create  default  print  racord 

JiCUpDefault  0 

{ 

PrlntRaeord  -  NewHandle  (140L,KvlD,  OxaoiD,  at]  ; 
Prflafault (Print Recordt ; 

} 

/*  Hon  the  menu  item  "Print"  Item  */ 


PRINT.CC  (printing)  409 


l'-n?rl-tl-em0 

If  mindPWloL'rint  -  FrrjT.Wl-dowfl  r  is  ihr;r€  a  ifindow  to  prln 

If    C  [?I  IjLl.UcKMiTti)  1 

H,jl  \.ru'r,^ri) ; 

iTi-iizfont.  -  PtOpenDcic[rrlni;tieMrd,ULJ.; 
rjtflpenragfi  J  Print  tort;  Lil.)  ,- 
Draw ropwl !  ifJciw  ( )  f 
DrCiO£eP4(79{.-rlL-.tFfjr  I.J  ; 
l?rCliiiH!ncji:(vTl:5cPort) ; 
Trrl^rlLft  (ft t  ntkacori:,  riT.j  HLj  ■ 
IriltCijijinrO  ; 


I 

DaisBflctiirjiLe  Tlii:H<-ft3n  -  NIL;  >jp  use  iMih'ly  dl '/r-r  i-l 

r^^tnBffcDtr  ayjtetr;  /,»  l;  I.  r     .  u  r^j.,  for  piety  ess 

fJatiSi^jPLr  FoTit  Pt  r ; 

TJiaBfirCcn  "  (DatiaafHsiidlefGatWRcJCc:;,  (WJn(i™TaPrinti ! 
]]L<5^:^;  (Tile  Ksf  Con)  f 
a^jiFLr  -  ^TheaefCefl; 

If  ^  iausC^tr  ->  Fl.iij)  /*■  rniri_^Eero  — >  for.t  V 

tcT.thaiidli;  -  (FQataPaiHar.dllsJGetHilurCiinCrflndowToPrintS,'      J*  Ju.jln 
HT.r;i:jti;FOL^t]liindla)  ,■  /•  to  u.];;;;  '/ 

boiitSLr  -  ^rontrrtndle;  /s  uj,e'rla"t  */ 

Sh.cvToM'.  a-^T.tPtr  -?  m,F^iTitrtr)  f  /■•.viiT'  •/ 

iJU  ni  ooJt  1  nd  1  e )  ; 

j 

Palhl.TI  (nuutl  tr  ->    Ici-iauci)  ,- 
l  jm  1  i  cJi  ('iJie  Rjt:  £   >.■: ) ; 


Appendfji  F:  HodgoPodg^  Source  Code;  C 


HP.H  (global  data) 
I 

Unclude  etypBa.t5> 
(Include  cquickdraw.h> 
(incLude  <f(jfit,h> 

Itieflrie!  screehmode:  axeo 
tdeflne  MAXsCAN  ISO 
fdaflna  ODAuxlool  19 
(define  PHafiagef  19 
Idflflna  HljiVar  0 
tdiifine  VDltrotFound  0)145 


/*  640  mode  '/ 

/•  Aiutlllary  Qyicitdraw 
/*  Print  Manager  tool  Kumber  */ 
Klnimun  Versian  for  then 


IdBflna  flUM_MEHUs  5 

tdsfina  NUM_WINDCWS  IS 

/'  Menus  related  defines  •/ 

fdefine  AppleMenylD  1 

tdefine  rileMfrnuID  2 

tdeflne  EdltHenuIQ  3 

♦dtflne  HrrfeHentilD  4 

tdefir.e  HlndcwsMenuID  5 
(dufino  FontsMcnuID 


/*  Nuntoer  of  menus  */ 

/*  KaxlmuBi  number  of  wSndnws  */ 


(define  UndoID 
(define  CutID 
(define  CopylD 
(define  Faat«ID 
(define  cleatiD 
(da  fine  ClQs^ID 


250 
Z^l 

254 
2S5 


/*  These  noxt  6  aro  standard  and  "/ 
/'  required  tat  PA  support  under  •/ 
/'  TaskMaster.  */ 


(define  AbeucID  2Bfi  /*  These  are  our  own  responsiblllcy  '/ 

(define  QuitID  151 

(define  OpenWID  258 

(define  SavelD  25S 

(define  ChooselD  2E0 

(define  SetUpiD  ZGJ 

(define  Print ID  262 

(define  ModelD  263 

(define  shflwFontiD  261 

(define  Mono ID  265 


/*  lonie  font  and  window  handling  stuff 
idtfine  HaxNanesize  29 


(dsfine  NufllLlnes  13 

t^edef  strucn  Datanec  ( 

char  "PlcKandf 
char  Blanlt,' 
ehar  Str[3Ql,- 
ehar  mstulf  [s]  t 
short  Flag; 
ehar  ELxtra,' 

t   DataReO,    'DataRecPttr,  "DataHecHandlej 


HP.H  (global  data) 
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/'  eama  thing  as  DataHac  but  ioz  Four  windowE 
typadel  struct  FoncDataRac  { 

ohsr  St  r[30f  ■ 
char  HMStijff[fi(; 
Byte  Flig,' 
char  E«tra; 

i  FDataRec,  "FDateRflcPtr,  "FDitaBecHandlo; 
typede-f  Int  Paqltadnata  [3zo]; 
typedef  struct  iJlrEntry 

[ 

Int  PadtedBytes; 
ward  Hbde; 
>  DlrELntryf 

typadef  struct  KainBlli  [ 

long  slieOffllock; 

char  IDstr[5],- 

word  Masteii4ode; 

Int  PiKelaPerScaniine; 

int  Nui!i5a4  lets; 

int     PaHetArr3y[16]  [16(  . 

int  WiimScailLlnes; 

DlrErtry  ScanHnaQirUOO]  ,- 

PackedDaCj  PacltedEcanLlnes  [200  ]  ; 

J  M=iiiBlk,  .^ialnBll(Pt^,■>•KalnalHHantlIe,■ 
'*  Da^'^H^L"  •'^        -™  with 
V 

ftfndel   aulog 

typ&def  struct  ItsmTempl^to  | 

Wow         iteiniD;         /.  itemTemplate  -  '/ 
Ract  IteriHectf  /•  ItBrnSemplate  -  ■/ 

word  itemrype;  /.  Itmnremplate  -  ./ 

P^int^r    ItHBDefici:,-         /-  itanTaFfllat*  -  V 

/.  H^^^.e  d.n..  the  di.l.,  t«,,plat.s  u..,  f„  standard  File         ...  put 
•/ 

itfndef  GetPutLlstLength 

tdeflre    Get PutListlenqth    On?      /•  set  to  IS  whf^i,  i 

lendif  -^t      /    iEC  to  it  which  Is  the  irj.x 

typeder  struct  GatPuttempUte  [ 
Sect  gpfloundsHEct; 
Boolean  gpVlsibla; 
LongWord  gptiafCon; 

f  ^"Tfr^"  ,      'JPl'^^nii^  [GetP^tLl strength ]  ; 
f  GatPutTemplate,     'GatPutTempPtr  ; 


Appendix  F;  Hodgepodge  Source  Code:  c 


Appendix  G 

Hodgepodge 
Pascal 


Source  Code: 


HP. PAS  414 

MENU.PAS  419 
EVENT.PAS  422 
WINDOW.PAS  42S 
OIALOG.PAS  429 
FONT. PAS  434 
PRrNT.PAS  437 
PAINT.PAS  439 
GLOBALS.PAS  443 
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HP. PAS  (main  program) 


pucgram  Hodgepodge; 

I  Hodg^Fodge:    fln  example  ARple  IIGS  Desktop  application 

I  WTitten  by  the  Applo  IlGS  D^veiopnent  Team 

I  T;aiiHldted  to  TML  Pascal  by  TKL  SysteniKr  Inc. 

I  Copyright   (cl  1996-87  by  Apple  Computer,  Irc. 

I  All  Rights  Reserved 


This  prograic  and  Its  derivatives  ace  licensed  orly  for 
use  on  Apple  computers. 

Hcrlia  based  an  this  progran  muse  contain  and 
ccnspicLiousl]^  til  splay  thia  net  ice. 

This  software  la  provided  for  your  evaluation  ind  to 
assist  you  in  developing  software  tor  the  Apple  lIGS 
computet. 

This  Is  not  a  distribution  license,  Dlstrltnitlon  of 
this  and  other  Apple  softvaro  requires  a  separate 
license.  Contact  tiia  soitware  Licensing  Department  of 
Apple  Computer,  Inc.  for  details. 

DISCLAIMER  OF  MARRA-STY 

THE  SOFTWARE  IS  PROVIDED  "AS  IS"  WITHOUT 
WARHANTY  or  MSY  KIKD,  EirHEJl  EXPRESS  OR  IMPLIED, 
WITH  ftESPECT  TO  ITS  MERCHAHTABILITY  OH  ITS  FITNESS 
FOR  AN¥  PAHrieULAR  PUEIPOSE.     THE  ENTIRE  RISK  AS  TO 
THE  QUAlITlf  AND  PEHFORMAMCE  OF  THE  SOFTWARE  IS  WITH 
YCH).     SHOtTLD  THE  SOFTWARE  PROVE  DEFECTIVE,  YCO  (AUD 
NOT  APPLE  OR  AN  APPLE  AtiTHORIZED  EtEPREBENTATIVE} 
ASSUME  THE  ENTIRE  COST  OF  ALL  (TECESSARi  SERVICING, 
REPAIR  DH  COBKECTIQN. 

Apple  does  not  warrant,  that  the  functions 
contained  in  the  Saftwara  will  meet  your  requi reoents 
or  that  the  operation  of  the  Software  will  be 
uninterrupted  or  error  free  or  that  defects  in  the 
Software  will  be  corrected. 

SOME  STATES  DO  NCT  ALLOW  THE  EXCLUSION 
OF  IMPLIED  KARMJJTIES,    SO  THE  ABOVE  EXCLUSION  KM 
NOT  APPLY  TO  ¥00.     THIS  WAKflANTY  GIVES  YOU  SPECIFIC 
LEGAL  HJGHTS  AND  YOU  MAY  ALSO  HAVE  OTHER  BIGHTS 
WHICH  VARY  FROM  STATE  TO  STATE. 


Pascal  UNIT  "HP. PAS"  :  Main  routine  and  tool  Inlt/shutdown  routines 
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Appendix  G:  Hodgo Podge  Source  Code:  Pascal 


I 


( KodgeFodgB  Apple  IIGE  Toolbox  Interface  Units  1 


(HoiiqePOElge  CodB  Units) 


IWlntfData, 
HPIntfPrac, 
KPIntEPdQs, 

clstuls. 
Dialog, 
Font , 
Paint, 
Wlrdcw, 
Ftlnt, 
Menu, 
Event; 

JiBjcttor  StirtDpTn-ajB  :  boolean? 

iBoutlne  to  start  up  the  Apple  IIGS  toolboji.    We  attempt  to  start  up  all 
the  managers  that  we  need,  checltlng  esch  timE  If  an  flrror  occurred  during 
startup.    True/false  Is  returriECi  By  this  routine  depending  on  Its  success. 
If  the  RAM-based  tciols  cannot  be  loaded,  the  user  la  prompted  to  Install 
a  syacein  dtet  and  is  given  the  option  of  trying  again  or  ejilttlng.  The 
latter  option  eslts  this  pjroeedure  with  a  False  result.    Tool  atartup 
trrora  result  In  a  call  to  the  Eystem  death  handier  (th?  bouncing  apple), 
with  a  code  showing  where  we  died  as  well  as  tho  actual  tool  error  number:.! 


con  It  DPForOuicltD  rav  -  $000 

DPForEventMgr  -  SiOO 

DPForctlHqr  -  ¥400 

DPForltneEdit  -  $51)0 

DPForHeruMijr  -  ^fiOCi 

CPForstdFllB  -  STCD 

DPForFontMgr  -  5800 

DPForPrlntHgr  -  S900 

TotalDP  -  SBOO 


(Needs  3  page?) 

INasds  1) 

{Needs  1) 

[Needa  II 

(Needa  1) 

{Needs  Ij 

(Need?  1! 

meeda  2] 

4 Total  direct  page  space) 


var  toolRec 
paramBlocii 
baseDP 


ToolTabie ; 

riieSec; 

Integer; 


label  1;  (Juat  for  onca,  let's  comnlt  the  cardinal  ain  of  using  the  GOTOI) 
btgln      [of  start tfpToola] 

StartCTfrtoolB  :-  tnlef  lAssujn  all  is  well  at  first) 


TLStartUp; 

CheckTool Error  ; 


(Inlt  Tool  Locator  ) 


HyHenio.iyTD  :~  MMStartUp; 
HTStsrtUp; 

ChecltTeolError  (521 ; 


Unit  Hanvory  Kanager) 
Unit  Mlsc  Tools  I 


(Allocate  memory  space  in  bank  0  lor  ijjteet-page  use  by  GB  Tools:} 
ToolsZeroPage  :- 

NewKandle  (TotalDP,  {Allocate  monory] 

MyMeiwrylll,  (ProcasE  (user)  ID) 

BttrBank+attrFlxed+attrLocked+attrPage,  (Attributes) 


Ptr  (0)!  ; 
ChE  clt  Too  I  Error  ( S3 1  f 
baseDP  :-  LoHord   (TaolaZeroPage^)  ; 

ODStartDp 

(basflDP  +  DPForQuiclcDraw, 

ScreenHode, 

HaxScan, 

MyM«raoryID) ; 
CheckToolError  {$4); 


(Start  In  bank  D  I 


(Address  of  zpag  t  3  } 
|E40  mode  I 
(Horizontal  line  slie} 
(Froceea  (user)  ID  ) 


HP. PAS  (main  program) 
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EHStarttj'p 

(basaDP  +  DFForEvantMgr, 
2D, 
Or 

Manx, 
0, 

200, 

MyHeniorylC); 
Cheek  Tool  Error   ($5)  ; 

(Slve  a  message  while  we  load  RAM  baseci  too-ls:l 


lAddreea  of  zpag  4  4 

IX  mln  elajcp 
(X  nia»  clamp 
liiin  clamp 
[y  max  cUmp 
(Process  tuser)  ID 


M&vaTo 
SetBaclsColor 

Drawstring 

ShowCurser; 


iia,  20)  ; 

(IS); 

('on«  Hsoiant  Please...'); 


{Mow  load  RW4  based  tnols  (and  HJVH 
toolRecNraTools  j-  14; 
toolRec. Tools (1 1  .TSKuin  :-  4; 
toolRec,TDal5[ll  .MlrLVaralon  :-  C; 
toolElec.Tools[2]  .TSN-jni  :-  5,- 
tocJRec.T(3ola[21  .MinVersion  !-  0,- 
too.lRec.Toi3lst31  .ISN'uni  :^  6; 
toDlRec. Tools [3  5 .HlnVerslon  0; 
toolRec.TtMSl3[4t  .^'SlfLnn  :-  14; 
taalSec. tools [4[ .MinVerslan  :-  0; 
tOOlHec.TDols[5f  .tSHLJH   ;-  15; 
toolHftc, Tools  [5J  .mnVErElon  :-  Of 
toolHec.Toola [6J .rSNura  16; 
toolHet,TanlB  [6|  .MlnVerslon  !-  Q,- 
tooiaecToolsni  .TSNum  19; 
toolRee. Tools e7] .MinVareioh  O; 
toolRBC.Tofllsfa] .TSNum  :-  19; 
tool  Bee. Tools [a ] .KinVerslfln  :-  O; 
toolRee,rpols[91  .TENot  :-  20; 
toolRee.renils[  91  .HinVersion  0; 
to<ilRec.rools[10|  .TSNum  il; 
tnniRec. Tools [101 .MinVeralon  :-  0; 
tanJRec.ToolsdlJ  .TSMuio  22; 
tonlRec.Toola [11] .KlnVerBlon  :-  Dj 
toolRecTools  [li  I  .TSNusn  :-  23; 
toolRec.Tools[li]  .MiTiVaralDn  0; 
toolRac,Tools[i3] .TSNum  :-  27; 
toolRec.TMlstU]  .HinVaralon  0; 
toolElec,.T&ols[H]  .TSn™  :-  29: 
toolRec. Tools  [H]  .HinVeislon  fl; 


patches  to  RM  tools!):! 

(QutcltDraw  II 
(Desk  Manajer 
(Event  Ksnager 
(Window  Manager 
IHanu  Man^qer 
{Control  Manager 
{QutckDrav  Mix 
(Print  Manacfer 
(Lire  Edit 
(Dialog  H^nd^er 
(scrap  Hansger 
(Standard  Pile 
(Font  Manager 
(I<i9t  Manager 


parajtiBloclt. pathname  :-  9' VSYSTEM/TOOLS' 

GET_FlLE_rN-FO  (patairSlocIt); 
If  toolErr  <i  0  then 

If  MountBootDisJs  -  1  then 

goto  1 
elae  begin 

StartupTools  false; 
Exit; 

end; 

loadTDdla  ItoolHtc)  ; 

CheckToolErroi-  fS6)  ; 

MlndStartUp        (MyMamorylD) ; 
ChBcItTooiError  ($7} ; 


(Kake  ajre  tools  avail) 


(Load  Lha  tools  I  nacdf 
[Intt  Window  Manager  ) 
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RfifreshDesttcop  [nil)  ; 


(Draw  ih«  destttnp 


1 


ctlstartUp 

(M^HemorylD, 
bsaeDP  +  DPForCt IHgr) ; 
ChocStTool Error  ($9)  ; 

LEStartUp 

(baseDF  t  DPForLlnaEdlt, 

MyKetiorylD)  ; 
ChadtTooLEnror  (S9)f 

Dlal&gStartUp 

(Ks*lenKiryID) ; 
chackTool Error  ; 

MeniiStartUp 

tWyMenmrylD, 

baseD?  »  ppForMenUMgrl ; 
ChficktroolError  ($a)  ; 

DeskStartUp,' 
CheckTool Error  I5CJ ; 

ShowP leas«Hd It ; 

SPStarcUp 

(MyMomorylD, 

bae«DF  +  DPForStdFllel ; 
CheckToolError  ($0) ; 
SFAilCepa  (true) ; 

QDAuxSta rtup; 
checlcrciolError  (SE)  ; 
HaltCucsorr 

FMStartUp 

(MyKEiTiDrylD, 

bsseBF  *  DPForFcmtMgrl  ; 
cheefcToolError  (SF) ; 

Llststartupf 
checkToolError  (SIO) ; 

SctapStartupf 
CheckToolError  1511}; 

FHStartUp 

(MyMeinorylD, 

bflseDP  +  DPForPrintMgr) ; 
Cfieclt  tool  Error  (S12); 

M^dePlaaseMait; 
initcursorf 


(J nit  Control  Manager 
I  Process  (usert  ID 
[Address  of  :pag  f  5 


Unit  Line  Edit 
^ilddress  of  zp^q  I  s 
iPracass  (ussr)  lo 


[Init  Dialog  Manager 
[Process  (user)  ID 


(Inlt  Menu  Managnr 
(Process  (user)  ID 
1  Address  of  ipaq  t  7 


(tnit  Dflsic  HanageE 

{Put  up  dialog  boK 

[Init  Standard  File 
[Process  (liHer)  ID 
(Address  of  zpag  4  E 

(I  want  lUenamet  In  all  caps 

Unit  QuickDraw  AuxU 

(Wristwatch  cursor 

(Inlt  Font  Manager 
(Process  (osarl  ID 
(Mdre53  of  ipag  f  9 

[Inlt  Llat  Manager 

(Inlt  scrap  Manager 


(Inlt  Print  Manager 
(Process  tuserh  ID 
I  Address  o£  zpsq  t  1 


(neniov«  dialog  box 
INgrmal  arrow  cursor 


end; 


(of  StartUpTool s> 


HP. PAS  (main  program)  d^7 


ptoceduTB  shutDownTooIs; 

{Routlnii  to  Bhyt  down  all  tha  tools  we  used  In  revurse  ordar  of  startup. 
Only  tools  which  are  currently  active  are  shut  dawn;  this  facilitates 
recovery  frem  an  error  condition  firnni  StartUpTonls.  [ 

begin      {of  ShutDownTooIs} 

If  wlftdstatus  <>  a  then 

HldeAllwindnw*;  iClose  all  windaiia  only  it  OK!    Takeis  aora«  time  1 

LlstShutDown; 
FMShutDouffir 
ScrapShucDown,- 
PMShutDown? 
QDAuxShutDown? 
srShutDown; 
HenuShutDown; 
DlalogShutt5own,' 
LEShutDown; 
ct  is  hut  Down,' 
WlndshutDntm; 
EMShutDown; 
QDShutCoun; 
MTShutDofcin; 

If  MMStatus        0  than  begin 

DispoaeHendle  (ToolaZeroPagej  ?     |Dm1  locate  tool  dlrectpage  apace] 
MMShutDown        (KyHemorvID) ;  (Do  this  only  If  OKI  I 

end; 

TLShutDown; 
end;        (of  ShutDownTool* 1 


BEGIN    lor  HMN  program  Hod^e Podge | 

InltGloiMl*;  (  inltUUe  our  globala,  raenua,  etc.  | 

if  StartUpToola  then  begin 
Setl/pDefavslt; 
SsttJpMenusf 
setUpWindoKs; 
MalEiEvent; 

end; 

ShutDownTooIs,-  {  shut  down  IIGS  Tools  [ 

END.       [gf  MAIN  program  KodgeEodge} 


Initlallie  IIGS  Tools  | 
Sec  up  prliit  dialog  | 
Set  up  menus  } 
Set  Up  windows  [ 
Use  apdlicatlon  \ 
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MENU.PAS  (menus) 


Hi>ilgef>odge :    An  ex^mplo  Apple  IIGS  Desktop  appllcatloa 

Written  by  the  fipple  I ICS  Develofment  Team 
Translated  to  THI.  Pascal  by  TML  Systems,  Inc. 

Copyright   (cj  19fl6-87  by  Appla  Conputetr  Inc. 
All  nights  EteBErVEd 


Bascal  CTNIT  "HEUB.pAS"  :  Kanu  bar  setup  and  mEru  item  handling 


IKTEBFACE 

USES 


WlntfData, 
HEIntfProc, 
HPlntfPdos, 

Glcb«ls, 

Dialog, 

Font , 

Paint, 

WindcvH, 

Print; 


{KodqePodge  Appla  IIGS  Toaibox  Interfaca  Units} 


{Hodgepodge  Code  Units] 


procedure  DoManu; 


{Ejtaeute  a  menu  item) 


proc^ure  SettTpMerLUs;     [ Install  jiienus  and  redraw  ir:enu  bar} 


IMPIiEHEHTATION 


procedure  AddToHenu; 

[E'rivate  routine  to  add  a  new  window  itsoi  to  the  'Mindoihis''  irtonu  afte-r  a 
IMW  window  has  been  drawn.  Increments  the  variable  HIndex,  a  ccunc  of 
th&  nuanber  of  windows  ourrejitly  open.  ^ 

Var  tlieWindow        :  GrafPortPtr; 
MyDiKtaHandla  :  WindDatsH; 

begin      [of  AddToMenu] 

theWindow  :-  FrontWindow? 

HindowLlst  [Hlndex)   :-  theHindaw; 

myO  at  a  Handle       WlndDataH  (GetWRefton  (thaWlndowl  )  ; 
insejftHIteii  (eiiirDdtaKdndle^'<.]innuStr  [1|  r^rFrF^HlndowaMenuID) ; 


MENU.PAS  (menus)  419 


il  WIndeK  -  0  then  begin  IThls  is  the  first  windowl 

DeleteMIteBi  {NoWindoHsItem) ;  iRemove  the  "ilLler"  Item) 

satHenwFlfifl  (SFF7F,  Windaw^nuID} ;     iHighlight  the  manui 
DraHHenuBari- 

and; 

CalcMenuslze  (0,O,HiindcwBKenulDl ; 

End;        (of  AddroMenuj 
procaduze  DoppEnltem; 

{Private  routlnB  which  Is  called  when  ttie  "Open...-  item  from  the  ■'Pile- 
menu  OR  the  "DiapJay  Font  -  Item  from  the  "Fonts"  menu  is  selECted 

(OpenWlnddw  will  tjetennlno  which  one  it  wasj .  If  too  icany  windows  ais 
already  open,  then  a  dialog  la  dlapjayeti.t 

begin      [of  DoOfienlteni I 

It  HIndex  <  LastWirid:  Chen 
If  □penWindow  then 
AddtqiMenu 

else 

else 

KanyHl  ndDla  I013 ; 
end;        {ot  DchOpenltem) 


procedure  I>a<}iiitlteiii; 

(Private  foutlne  to  set  Done  flag  If  the  "Quit"  Item  selected) 

tie^ln      (of  DoOultlteinl 

Done  !-  true; 
end;         (of  DoOMltltenl 


procedure  DoHindow  (ItamKum:  Integerl ; 

{Private  routine  which  brings  a  S|»olflq  window  to  the  front  of  the 
desktop,   in  response  tc  s  aelactlon  Iran  the  "Wlndohrs"  jnenu,  ( 

var  cheNlndowi  GrsfPortPtr? 

begin      [of  DoMlndowf 

theWlndow       WlndowLlst  titemMiai  -  FlrfitWindltem]  ; 

SelectHlndoM  (theWlndow)  ; 

ShqwWindoM      (theWindow) ; 
end;        [of  PoWindow) 
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piDcadura  DoMenu; 

[tro(*darB  to  hsnctle  sll  menu  selections.    Examines  the  Event. TaakData 
Eiianu  Item  ID  word  frem  Ta£KMaere£  jfironi  Event  H^i^afjer)  and  calls  the 
appropriate  rnutlne,    KJiJ  le  the  routine  Is  running  the  menu  title  Is 
still  hlghllghtficl.    ATter  th«  routlna  rettirna,  we  iinhlllght  tha 
Kieny  tltleil 


it«nNuin 


Integer; 
Integer; 


tHgln      (of  DoManu) 


menuNuin 
it«EiiNum 


HiHord  (Event ,  WT.TaskData) ; 
LoHord  (Event.wiETaaKData]  ,* 


Case  ItonNuni  oZ 
Mnutltan 
□penltEjD 
Closelteni 

ChoosePTtein 
PagaSet  Item 
^rlntltem 
Qui tit em 
Undgltem 
Cutltcin 
Copjrltem 
PasCEltat 
Clearltac 
Font  Item 
Monsltem 
stharwlsa 

HaHindoW  (IterJluni)  s 

end; 


DoAbout Item; 
DoOperltejn; 
[XjCloseltem; 
Dosaveltegr; 
DoChooserlCBJTi; 
DoSetupltemf 
DoPrtr.tlt&m; 
DoOuttlteur; 


DoDpenltem; 
□osetMOriai 


HlllteMenu  (ralBQ^xonuNiiu)  ; 
and;        iQt  ^otieiM] 


WnblghlLqht  the  nenu  title! 


inocedure  SetUpMnuB; 

IPncedure  to  Install  our  ninnu  titles  and  their  ItenLS  in  tbe  system  menu 
bar  and  ts  redraw  It  so  we  can  fee  triein,) 


var  height  ;  Integer; 

begin     (cf  SetUpHeriLis  I 
setMTltleStart (10) f 


(Set  Starting  position  of  menu) 


InBerthfenu  (NeifMenij  ISFontMer.uStr      [1]J,0);  (Fonts  ?fcnu 

InsertMenu  (NetiMenu  [EWlndoWHenuScr  [l]},0)f  [Window  Meinu 

InsertNenu  (NewKenu  [BEdltftenuStr      [11  KOI  f  lEdlt  Menu 

InaertMenu  IHewHanu  linienanustr      (1]J,0),-  (File  Menu 

insertMenu  INeHMonu  ISAppleMenuStt    [11},0|,-  (Apple  Menu 


FlxAppleKenu  (AppleMenuID)  ; 
height  :-  FlifMenuBar; 
DratMenuBar; 
•nd;      (of  setupMenkis) 


{Add  DAb  to  apple  nienU  ] 
{Set  sizes  of  menus  ] 
{ . . . and  dr^w  the  menu  bar [ 1 


ins. 
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EVENT. PAS  (main  event  loop) 


UNIT  Ev*nt; 


KodiiePotiqe;    An  example  Apple  riG3  DasKtop  application 

WEittBn  bv  the  Apple  IIGS  DeveloFmant  Team 
TranfiUted  to  TML  Pascal  by  TML  syistems.  Inc. 

Copyright   (cl  1586-87  hy  Apple  CoirputEr,  Inc. 
All  Bights  Eies&rv^d 


Pascal  UNIT  "EVENT. PAS"  :  Event  loop  and  dlEpatehl nij  rmjtlna 


INTERFACE 


USES 


KPIntfDita, 

HPIntrProc, 
[JPIntfPdofi, 

clotals, 

DialcQr 

Font, 

Paint, 

Window, 

Print, 

Kanu; 


I HodgePofige  Apple  ITGS  ToolboR  InterEacB  Units! 


[ ttadijepQdgG  Code  Urlta) 


procedura  MalfiEVent;      (Main  event  handling  loop  which  repeats  until  Qultf 


IMPLEMEMTAriQJJ 


procedure  KaLnEvenc; 

(Haln  •vent  handling  routine  whtch  loops  until  the  Done  flag  li  set  Isy 

selection  of  the  "Quit-  item.    Wa  call  the  wlncios  Manager's  TasScMaater 
routine,  which  calls  the  Event  Hansger's  GatNexcEvent  rnutino  and 
handles  window  reaiie  tra citing/ resizing,  window  mo'Veraent  tracKlng/reaiilng, 
window  aetiviitlnn  (bringlftg  to  front  by  clicking  or!  an  Inactive  window), 
among  other  things.    TasKMaster  rat urns  control  to  us  when  the  user  has 
cllcKed  a  window's  GcAway  chacS:  box,  or  when  the  user  has  selected  a  menu 
item,  either  with  the  mouse  o*  With  an  equivalent  Solid-Apple  Iteystroke 
sequence.  1 


var  code  ;  integer; 
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Appendix  G:  Hodgepodge  Source  Code;  Pascal 


procBdure  ChackFrontW; 


[Checl!  to  whom  the  front  wlndoH  belonijs  to  (ue  or  a  Dask  Accessotv  IDA)  ) , 
and  If  It  belonga  to  us,  whether  it  Is  appropriate  to  disable  (dlml  certain 
menu  items  jsuoh  as  thfl  Save  Item)  or  to  enable  them.     Private  routine.) 

var  thaWlndow        :  GraEEortPtrj 
iryDataKandle  ;  WindDataK; 


prQCed.ure  Bl  sable  It  eras; 

[Private  routine  to  disable  Idiiti)  certain  menu  titles] 

begin      [ot  Disjrbleltenis} 

DtaableMltem  (SaveRsIten) ; 

Dls-abl&MItem  {closelteiTi]  ; 

DlsableMItem  [Print  JteKij ; 

D 1 eableHItam  1 PaqeS  et  E  temj ; 
end;        [of  Dl  sable  It  eirsl 


procedure  Enableltcms; 

(Private  routine  co  enable  iundlm]  certain  menu  titl«sl 

begin      (of  Enableltffins } 

EnableMItem  (Sai;eA3ltei?)  ; 

EnJiblEMitem  ( Close  I  tern  1  ; 

EnablEHItem  (Frintltem) ; 

Enab 1  eHItem  (Pageset I tern ) ; 
end;        (of  Enable I terns) 


procedure  DlBablehll; 

Ifrivata  routine  to  dlaabie  all  menu  titles  for  Dask  Accessory  fOAi  t 

begin      [of  DlsableAll) 

SetMenuFlBB  (^ODBD, EdltHenuIDJ ; 

DrawMsnuBar; 

oi£ableIteF.E; 
end;        [of  DiubleAllI 


EVEhJT.PAS  (main  event  loop) 
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procsdure  SettlpForAppM; 

[Called  :f  an  application  window  (onral  1=  rh=  ^ 

i»9ln      {of  SetUpForAppwi 

SetMenuFlag  (50DB0, EflltMenulE] ■ 

DrawMenuBar; 

SnelaieitaiTta; 
encif        I  of  SetUpForflppWJ 


procedure  SetUpfotDAW; 

if  .  D...  .i,,,,  1,  ^^^^^^^^^ 

tesLn      [Df  SecUpForUAWI 

Dlaableltecia; 

EnableMItem  (ClnseltemJ; 

SetMenuFlag  1SFF7F, EditMenuIO) ■ 

DrawMenuBar; 
end;        (of  SetLrpFoxDAW) 


±»5ln      (of  Check FrontW] 

thjewindow  :-  FrontWIndow; 

If  theMlndoM  -  laatWindow  then 
Exit; 

If  thawindow  -  nil  than 

DisihleAll 
else  begin 

If  GetSyaWFlag  (th.Window)  -  true  then 

SatUpforDAw 
«lse  begin 

DlMblemtem  (SavEAsIeejBj 

era; 

end; 

lastWinaow  theMlndow; 
end?        (of  Check FrontW] 


begin       ( jjf  ffalnEvetitl 

Event. wmTaBkHaai:  r-  SDDOmFPr.  j.n 

Done  .  r,™  '^^^^     ^ll"-  ya^kMaacer  to  do  evsrytMngl 

f«l",  (Done  fla,  «in  be  c^it 

ropeit 

check FrontW; 

eode  :-  TaskHaater  (SFFFr.Event j - 
case  cndo  of 

HltiGoAi^ay      !  DoCloaeltem; 

winSpeciaj, 

i'lTiHSnuflar    ;  EJoMefiu; 

&nd; 

until  Done; 

laf  HalnEventJ 


END. 


Appendix  G:  HodgePodge  Source  Code:  Pascal 


WINDOW.PAS  (windows) 


I" 


HodgePodtie !    An  example  ftpple  lIGS  Desktop  application 

Written  by  the  Apple  IIGS  Devolopitient  Team 
Translated  to  TML  Pascal  by  THL  Systems,  Inc. 

Copyi-lflht  (c|  19SS-a7  by  Appla  CtsmputEr,  Inc. 
All  Rights  R^servfld 


Pascal  UNIT  "WINPOW.PflS-  :  Routines  to  open  and  close  wjndawa 


^,  +) 


INTERFACE 


KFIfittData, 
fiSlntiProc, 
HPlnttPdos, 


( H0{igaP(idgB  Apple  IIGS  Tuolbos  Interface  Dnltsl 


Globals, 
Dialog, 
Paint, 
Font; 


IHodgePQilQe  cod*  UnltBl 


pneeduFfr  DoCloseltm; 
pivcedurE  HideAI  IWlndQws; 
fUnctlqr    QtienHlndow  :  boolean,* 
procedure  SetCTpWlndo>^s; 


ICloBes  etirr»nt  frontmnst  window  ) 
1  closes  all  windows  on  the  desktop  } 
(Tries  to  open  a  font  or  picture  window  I 
(Initiaiiie  varlablee  for  stdciiin^  wlndowsl 


IHPLEMEfrTATIOW 


I 


nywlnd 
wXof fsst 

iSlzFc£ 


Parantiet; 
Integer; 
Inte^er; 
Ssetf 


pincedure  GoCloseltenir 

{This  procedure  clasea  tha  frontmost  window  and  deallocatea  all  of  Ita 
asEoelatod  storage.    NDA  windows  are  aupported  for  when  this  procedure 
Is  called  by  HideAllMlndows  when  eitittlnq  KodgePQCige ,  [ 


var  thBHindow       :  GrafPortPt  r,- 
inyDBtaHaridle  ;  WindlJataH; 
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pmcedurt  AdjWlnd  (thaKintjow:  GrafPortPtrl ; 


(Pldds  the  window  dBsignatad  by  theHlndow  and  ramoves  It  Icaa  the 
Windowllst  and  returns  tha  poaltlon  In  tha  window  Uet  wh»ra  li  was 
round.    Private  function. | 

vat    1  :  integer," 

theone  :  integsr; 

begin      |of  Ad]Wird| 

{Find  the  indes  of  the  flrafportptr  of  the  windaw  being  deletadM 
1  riracWlnd; 

while  WlndowLiat   (i]  <>  theWindow  do 

Ire  (ij; 
theOne  1; 

(RemoKe  correHpondlng  Item  frem  the  WINDOK-rneriu-  ] 

If  HIndait      1  ther,  be^tn  [Last  wlndo«-™clal  casa} 

InsertMItflm  (^NnWlndStt  [1|  ,  FlratWlndltein  +  theOnE,MIndowaMemiIDl  • 

EatMenuFlag   I^D(JBO,WlndnwsHanuIDJ ; 

flrawMenuflar; 

wXoffsat  :-  20; 

wYoffset  IJ- 

end; 

DeleteMItem      (Fl rstHindlton  +  theOna}; 
CalcMfenuSiie     {0,  0,winijowsMenuIDl  ; 

Inc^a"^^^  "^^^^  fi-ifPortptr  of  the  Ill-fated  wlnd<.w:j 

while  i  <  LastWlnd  do  begtr 

MindowLlKt  [i  -  I]   :-  WlndoulUt  fil; 

Inc  (1); 

end; 

[Renimber  the  MIlJDOW-irenij  it  airs;  J 
for  1  :-  theOne  to  LastMlnd  do 

SecMltemiD  (riratWlndltem+l-l  fnew  iDj     ,     FltstWlndltem+1  [olrf  ID) J; 
end;        (of  fld]Wlnd| 


be^ln       (of  DoCloseltenv} 

thetflndow  FrontWlndow; 
CIoaaiiaAtiyWiiiPtr  (theWlndc™)  ; 
If  IsIoolError  then  begin 

Adjwlnd  (theWlndoH) ; 

JuyDacaMandle  MlndDat^H 

Dlspoeelfisndle 

CloEewlndobr 

Deo 

end; 

er.d;        (gf  DoclosBiteml 


[GetHRefcoii 
(Handle  (myDatsHandlet  ( ; 
(thewindow) ; 
(Wlndeji}  ,- 


Ut  wasn't  m  mm  vlndow] 
(Update  WINDOW  menu) 
(thaWlndow)  ]  ; 
[Deallocate  storage | 
[Hemova  the  window} 
(Irden  Intn  window  list) 


proeadur*  «i deAll Windows,- 

Eoclcaertem  to  olnse  the  frontmn.t  wlMnw  [«hlth  has  the 

liill  W  "  ,    "  '^^"^'^  f*°ntmoat  ona)  until 

thera  la  no  frontmoat  window  anyniore;  la,  ther«  are  no  more  wlndc™,.} 

begin      (of  Hi deAll Windows  J 

While  Front Window  <>  nil  do 
Dacioseltan; 
end;        [of  HideAllWindoHS ( 
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Appendix  G:  HodgePocfg©  Source  Cod©:  Pascat 


(Tries  to  opsn  either  a  font  qi  picture  clndow,  depending  on  the 
Event.TaakData  teturnea  (rar  TasWasiEf  (which  gat  iz  ffusn  the 
EvBr^t  Manager).    True/false  ta  recuraed  depending  nn  whether  a 
wlrdnvi  tuis  actually  opened.    Note  the  way  In  which  the  different 
functions  are  callftd  in  the  If-then-else  structure  below.  Each 
function  tries  to  do  what  Its  name  Ittiplles,  and  the  true/false 
result  that  each  retiitue  la  uaad  tn  determine  If  the  fieit  logical 
function  should  bfl  called.! 


function  DoTheOpen:  boolean; 

IThla  function  ttlea  to  o|pen  a  window  and  returns  true/false  depending  on 
Its  success.) 

var  theMlndow  {  Gra f PortPtrf 

myDataHandle  :  HlndQataH; 

th^enuStr  :  Str2S5; 

ourFiintlnfo  s  FontlnfoHecord; 


be^in      {of  DoTheOpsn) 
DoTheOpen  false; 


myDat a Handle 


WlndDataH  (h'ewHandle 


If  IsToolError  then 
EKlt; 


( s 1 z  eo  f  {Mi ndDataRec ) , 
MyHefRoi'yID, 

attrLoclcfld  +  attrFlxedr 
Ptr  (OMt; 


with  irywlnd  do  begin 


end; 


parainlength 

MFrameSlts 

wRefCtsn 

SetHeCt 

wColor 

WYOrigln 

HXOrigln 

wDataH 

wQataH 

wKaxK 

wKaxW 

wscrollVer 

mScrolIHor 

wPageVer 

HPageHor 

ulnf  ottefcon 

winf  oHeight 

wFrameDef Proe 

wlnfoCefProc 

upiane 

wStoraga 


-  3li«of  (Par^Llstl; 

-  SDDAO; 

-  longlnt  IrayDataHandle) ; 

nil; 
0; 
0; 

les; 
S'la; 
200; 

4; 

16; 
40; 

0; 

0; 

nil; 
nil; 
-1; 
nil; 


thflManuStr  !-  coneat  (•--', 

myneply .  f  llenasie, 

IntTostrlng  (Flrstwlndltem  +  windeKl, 
"\0."}; 


Vlth  rnyDataHandle*"  do  begin 

Name        ;-  irryReply .  filename; 

MenuStr  :-  thaHenustt; 

Menu  ID         Flrstwlndlteui  t  Wlndex; 

end; 
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if  Loword  (Event .umTaskData)  -  Ffj/itltcm  then  begin 
IWe'ie  opening  a  font  wlndaw:) 
iaywlnd,»iCcint[>EfPrcic  :-  IDlspFontWirdcw ; 
with  irytJataHaiuile*"  do  begin 

fLag  1; 

theFont       Des 1 redFont r 

IsMono    !-  IsKonoFont; 

end: 

ruBtailFont  (Oe5ire{lFpnt,a)  f 
GetFontlnfo  (DurFont Info) ; 
MyWlnd.HDataH       15  (KimLines+ll  * 

(OarFont  Info, ascent  +  ourFont Jnf O.deeeerit) ; 
[Call  to  A  rindMaxWidth  procedura  would  be  placed  here  to  eat 
th«  HyHind.wCataK  field  ta  length  ai  the  longest  line  af  text.] 
Erid  eiSE  begin 

(Mo'ra  opening  a  picture  window;] 
Biywlnd.wCantDEfProc  :■■  SPalnt; 
with  myDataHandle"  do  Ljegin 

flag  0; 

plct  PlctHndlf 

end; 

end; 


Hlth  myHlnd  do  begin 

wTUle  :-  *myDataHaniile**.Nanier 

SetReCi;  (xPoslt ion, wXof fact  +  iSiiPos.hl, 

wfoffaet  +  islzPos.vl, 

wXoffset  +  l£lzPQS.h2, 

wYoIfset  +  iSlzFss.vZ) 

end; 


wKoffset  :-  wxoffsat  +  20; 
wYoffMt  :-  HYoffset  +  II; 
if  viyof/BEt  >  lio  their 
wYnffaet  :-  12; 

(How  create  the  iflndow:] 
thuHlndow  :-  NewHlndcw 
SecPort: 
SfltOrlgiriHaBk 

InltCursor; 
PaTheOpen  :-  true; 
end;        I  of  Dotheqpenl 


^update  global 5  which  affaet  nE^  wir^dow  pos} 
4 Cause  stacking  Affect  | 


(ijiyWind)  ; 
(theWlndow) ; 
(SFFFE,thoWindow) ; 

{Go  bade  ts  the  arrow  cursor) 
(Indicate  successful  cranpletionj 


begin      {of  Opant41ndow| 
OpenWlndow  false; 

1£  LoWord  (Event .wmraskDataJ  =  Font It em  then  begin 
If  DoChoosoFont  then 
If  DoTheOpen  then 

OpenWindow  true 
end  els&  begin 

If  AsicUfer  then 

if  DoTheOpen  thon 

OpenWindow  :-  true 

end; 

end;        (of  Dpenwindau] 


procedure  SetUfMlndnua; 


begin       (of  SetUpHlndow£ ^ 

wXoffsot        20;  {Initial  window  position  offset  used  for) 

wYoffset  :-  12;  [...stickln?  the  windows,) 

SetRect     (iSliPoa,  H>,2D,350,  BOj  ; 

end;        (af  SetUpWjndows) 


END. 
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Appendix  G:  Hodge  Podge  Source  Code;  Pascal 


DIALOG. PAS  (dialog  boxes) 


WIT  Dlsloy; 


I 

Hedge; Chdqe:    An  ex3itip].e  tipple  lIGS  Dealctop  application  | 

I 

Hrittan  by  th«  Apple  IIGS  [Isavelapnent  Team  | 
Trans 1 at ed  to  THL  Pascal  by  THL  Systems,  Inc. 

Copyright  (cj  1?9E-B7  by  Apple  Conputer,  Inc. 
All  Rights  Etvacrved 


Pascal  UNIT  "DIAlOC.PflS"  :  Dialo?  and  Alert  bon  dramlna  routines 
 +1 


:»TERFflCE 
JS2S 

HFIntfDats,  [HodijeFedge  Apple  IIGS  Toolbox  Interface  Units) 

HPIncfPjTDC, 

tfPIntfPdoa, 

Globals;  ( KodqeFodge  Code  Unit] 


ciirrenclcenil  :  ItemTeraplate; 

cufre/icltemi  :  itsnTeraplste; 

origEort  ;  Graf PortPtr; 

cisgwindptr  :  GrafPortPtr; 


irscedure  DaAtaokitltai;; 
sroceduxe  ShowPleaseWalt ; 
jrocedure  UideFleas^iWalt; 
function  CheckDi skError 
jrocedufB  CheckroolError 
function  Maunt  Boot  Disk  •, 
irecadure  KanyWlndDLalcq; 


(Where  :  Intsqer)   ;  bool^^n; 
(Where  :  Integer)  ,> 
Integer; 


(About  Itan  in  apple  n^nu 
IPlease  Wait  during  Inlt 
I  Erase  the  above 
tAlett  it  ftapas  errar 
IDeath  is  tool  error 
lAaSt  boot  disk;  1  if  OK 
(Walts  until  OK  clltKed 
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IMPLEMENTATIOM 


procedur*  KaiteATamplate  (Thsramplste  :  MejxTanpPtr;  The-Str  :  Strlngpti-J; 

( Private  routine  which  cj^estes  in  alert  tanplate.  I 

beqln      ^at  MakeaTemplatel 

with  TheToniplate*  do  begin 

Socaeet  latHoundBHect , 120,  JO^  520,  BO)  ; 

at Alert  ID  ISDO; 

atstagel  seO; 

acstagej  SBQ; 

3t5taqe3  $eQ; 

atstiiqe4     :-  580; 

atltffliiX      :■•  Scurrentltaml; 

atltemi      :-  @curre.ntItLeni2; 

atlteraS  nil; 

end; 

with  currentltanl  da  begin 
Itemia  i; 

SetRect       (itanBact, 320,^5, 0,0); 

itemType         10;  (Buttton  Item  constant  >lcj 

ItemDeser  ;-  B'OK'; 

IteniUalu*>  Q; 

itemFlag    •»  0; 

ItemColof  nil; 

end; 

with  current Item?  do  begin 
Itemld        ■-  2; 

SetRect       (lEaBlHetrt,l!,ll,  639,199); 

Iteratype         15  +  SBOOO;   (Disabled  Static  Text  Itani  mnstant  >!<} 
ItomDeEcr       Pointer  (TheStr) ; 
itEmValue  :-  0; 
ItanFlag  O; 
ItomColDr  :-  nil; 

end; 

ftnd;        (of  MakaArempLita 1 

procecture  showpieaseWait; 

{Displays  "Elease  Walt.,."  dialog  bo*  on  the  acrBen,] 
var  r  :  reet; 

begin      (of  ShowPleaseWalt] 
orlgPort      t~  GetPort; 

maijVfindf'tr  :-  GetKeHHodalDlaloqi  (iPlaWtTemp] ; 
SetHe-ct   (rflO.lS,  640,  JODJ; 

NewDItea,  (ra.gwlndPtr, ISDJ,  r,  IS,  9<  Pl»as6  wait  whll«  we  eet  thing*  «p  ' 

D,0,Eolnier(0]  ) ; 
aegl  nUpdat  e  (iragWi  n  dPt  r )  ; 
DfaifDlalDg     laisgHlndPtr} ; 
EndLTpdat  a      (msgWl  ndp  t  r}  ; 
end;        [of  showPleaaeWalt ] 


pracedura  HldePleascWalt; 

iHBinoves  -Pleas*  Male...  -  dialog  box  from  the  screen.! 

begin      (of  HldeF leaEeHalt I 

CI  DssDl  a  log  (losgWi  ndPt  r)  ; 

SatEort  (orlgPort) ; 
end;        [of  HielePl«afieWait} 
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Appendljf  G:  HodgePodg©  Source  Code:  Pascal 


funcCloTi  CheckDlsJtErrar   (Where  :  Intogerl   :  bonlean; 


[iriia  rciitlne  chocks  tf  the  last.  PrnDOS  speratlon  caused  an  ertcr.    If  so, 
ihen  ue  change  ttie  cursor  to  the  arrow  cursor,  put  up  a  stop  alert 
iJialog  box  with  the  text  of  the  Error  message,  change  the  cursor  back  to 
thB  wrlstwatch,  and  return  TRUE  as  the  function  result.    If  there  wsa  no 
disk  error,  then  tfe  simply  return  with  FALSE.  \ 

var  itEuiCl Icked  j  Integer; 

ourAlert  :  MertT'ec^Ute; 

OLirErrStr  :  str255; 

atirwherescr  :  str255; 

ourfltilnq  :  scr?5S; 

dlslcErrNuin  :  integar; 

bsgln      jof  CheckDlakErrorl 


dIakErrNuir 
checkoiskError 
DurErrStr 
ourWIiereStr 


toolErr;  the  std  C-llke  toolerr  var  for  P/16) 

(dlskErrNum  <?  0);  [Assign  fuhctlon  result} 

■XXXX';  (Set  string  length  byte! 

•  XX',-  (Set  strln?  length  byte! 


if  dl 6k Err Kim  <>  0  then  begin 

(**'  If  desired,  get  disk  err  string  hers] 
IntJHeic  (dlskErrNum, 

StrlngPlr   (InnglnL    (l!ourErrStr)   +  1), 

4);  iSet  ASCII  error  I  £tr  > 

intZHeK  (Where, 

StrlngPtr  (langlnt  (laurWhereStr)  +  II, 


21; 

oucString  :-  ooncat  ('Disk  Error  5', 
ourErrStr, 
'  occurred  at  5', 
ourWhereStr, 
' . ' )  ; 

KakeATflinplata  (Sourfclert,  SourStrlrg)  ; 
In  It Cursor; 

ItomClicked  :-  StopMsrt  (SourAlert,  nilj  j 
[DO  not  restore  watch  cursor  } 


4  Set  ASCII  whare  t  str  I 
(Build  our  error  mesg  I 


[Build  our  alert  tmplt  J 
[Set  arrow  cursor  1 
[Draw  dialog  t  wait  [ 


end; 


end; 


|o£  CheckDiskError} 


procedare  HanyWlfiiJDlalog; 

(Displays  alert  dialog  (triangle  with  "!")  with  a  meeseije  about  no  more 
wlndowB  being  allowed  open,     Handler  mouse  events  until  the  OK  button 
Is  clicked.    Then  the  dialog  box  Is  removed  and  we  return. | 

Var  ourAlart        s  Alerrtan^late; 
our^cring      :  BCi2ii; 
ItenClickad  :  Integer; 

beqin      {of  HanyHlndQlalog I 

pprstring         ',-  'NO  msre  windows,  please.'; 

MakeATemplate   (lourAlert, ^nurStrlng) ; 

ItomCllcked  CautlonAlert  f8ourAlert,nll!  ; 

end;        [of  Hanynlndllialog ] 
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procedure  ChecfcToolErrcr  (where  ;  InteqerS; 

illils  routine  cheeks  if  the  last  tool  called  returned  an  error  code. 
If  not,  then  we  Jufit  return.    Else,  we  exit  to  the  systatn  death 
hsndler  routine  which  prints  our  fitting  shcuclng  whore  we  bojtibed.  The 
death  manager  adda  the  tool  error  ende  to  the  end  at  the  fitting,  and 
puts  the  bouncing  apple  on  the  screan.} 

var         toQlErrorsawe      !  Integer; 
deathMsg  :  string; 

bsgin      (of  ChecltToolError] 

toolErrorSave  ToolErrorNiim; 

deathHsg  :»  ■  At  SXXXK;  Could  not  handle  error  S',- 

ir  toolErrorSave  <>  0  than  b^ln 

(Add  the  heji^ln-ascli  number  to  th«  strincjjl 
I;it;!!Hex  [Wh«r«,  strlnqPtr  (longlnt  tSdeathMsg)  iE| ,  4 ) ; 

[Halt  «ith  pur  death  msssaqe  string  and  tool  error  tnde:) 
SysFallHgr  (toolErrorSave, deathMsg) ; 

end; 

end;        [of  CheckToolErrort 


function  MO  tint  Boot  Disk  :  Integer; 
var 

proraptstr  ;  string; 

oltstr  :  striog; 

cancelstr  :  strir^g,- 

volstr  :  string; 

gbvParame  :  PathNameHee,- 

begin      lot  Mount BootDi sic l 

promptStr        -PlEase  Insert  the  dlslt'; 
oliStr  :-  'OK'; 

cancelStr  :-  "Shut  Duwn'; 
ghvpirims. pathname  :-  fluolstr; 

GET_B00T_VOL  (gbvParanis)  ; 

KountaootDlBlt  :-  TlMount Volume  (174, 30, promptStr,  volStr,ol!Str,  canoeist r) ; 
end;        (of  Mount Boot Dl sk t 


procedure  DoAboutltetn; 

var  aboutDlog    s  GrgfPortPtr; 
r  !  Beet; 

Itemuii       :  integer; 
applelconP  j  ptrl 
ApplalconH  :  Handle; 

begin      (of  Doflboutlteml 

(Draw  the  dialog  box  on  the  screen: I 

SetRect   (r,  146, 20,05, 193); 

aboutDlog  :-  NenKodalDlalog  (t, true, 01; 

[Add  an  QK  button  to  it:( 
SetRect   (r, 1S3, Q, 0) ; 

(JewDIcepi   [aboutDlog, 1, r, Buttonltem,  9'OK'  ,0,  0, nil)  ; 

(Add  the  Apple  logo  tq  It : I 
SetRect         (r,  20,135,0,0}  ; 
applelcnnP  :-  BApplelcon; 
applelcohH  SapplelconP; 
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MetiDltem  (sbouLDLog,  3,  Fj  letsBltem  t  ItefflDisable,applElconH,  0,0,  nil!  f 
[Simply  urita  the  text  rather  than  create  a  bunch  o£  dlaletg  Itams;) 


^etPnrt 

(about D Log) ; 

SfltForeColor 

m } 

^EtBAckColoF 

(151; 

setTestFace 

(B); 

DraHStrinq 

r 

Hodgepodge'}  r 

Set Text Face 

(01 ; 

HoveTa 

(40,17); 

Drawstring 

!■ 

A  potfiQurrl  of  routines  that'); 

(40,31) ; 

dotionstrata  many  features  of'lf 

Drawstring 

I' 

(40,471; 

Drawstring 

{' 

the  flpplB  lies  ToolB,'); 

MoveTo 

(40,  67); 

Ofawstrirg 

(■              thsf  Apple  IIGS  Development  Team'); 

KOV«T(3 

Drawstring 

(TranBl 

ated  to  TML  Faecal  by  IML.  Systems'); 

HOVBtO 

(40,87); 

Drawstring 

[' 

copyright  Apple  Computer,  Inc. '),- 

MovelQ 

(4D,117) 

Drawstring 

(' 

198fi-87,  All  rights  reserved'), ■ 

MaveTo 

(<!a,i27) 

Drawstring 

(' 

V4,0        23-Sep-97' ) ; 

ll*t  Dialog  Manager  handle  all  events  untU  the  OK  button  Is  cllcXeij! ) 
IteeiHlt       ModalDlalog  (nil); 

{Repove  the  dlalog^  box  from  the  screens) 
CloseDlalog  (aboutPK^j ; 
end;        iof  DoAboutltem) 


ESD. 
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FONT.PAS  (fonts) 


UNIT  Font; 


Hodgepodge:     An  exairiple  Apple  IIGS  Desbitop  applleati 

Wrltteji  by  the  ftpple  IIGS  Devfllofniene  Team 
Tranfllitsd  to  IML  Pascal  Ijy  TKL  Systams,  Inc. 

Copyright  (c)  1SB6-B7  by  Apple  tomputer,  Ine. 
All  Rights  He served 


Pascal  UNIT  'fONT.PAS'  :  Font  window  dirawing  routines  | 
     ^1 


INTERFACE 
USES 


HPlntflJata,  IHcrdgeFodge  Apple  lies  TanJboK  Interface  Llnita] 

MPlntiTProc, 

HPljltfPdOB, 

Gldbali;  (Hodgepodge  Code  unit  J 


pi-ocedurt  DlspFcntwindox,-  ,craw  fact  >,lnd(o«  cantents  1 

function    DoChmiasFont:  txmlean;  [Dialog  for  asklnfl  font  Biit,  ale.  1 

procedure  DoSetHono;  r*..-.  ri,„  ..j    .r    .                Btc, , 

J  isata  rjsg  ind  affect*  menu  Itflin  ( 

procedure  ShowFont   (theFontIS:  FontID;  iaM=no:  boolean);     (Actually  d«»  font) 


IMPLEMENTATION 


praceduTB  DlapFontWlridow; 

(Thla  Is  a  Definition  Proeedute  used  to  draw  ttie  contents  of  a  Font 

Var  UnpPort  :  GrafPortPtri 

myDataHandle  !  wtndDataH; 

begin      (of  DlspFontWlndow! 
tmpPort  :-  GetPort; 

siyDataKandie       wlndDaiaH  rCetWHefCon  (tiBpPort}); 
with  myDataKandle^*  do 

ShoHFonc   (thaFdnti IsMono) ; 
end;        jof  DlspFontWlndow) 
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(Display  the  Font  Manager 'a  dUJog  lor  the  user  to  select  a  font, 
font  aljs,  and  font  style. 

Ttie  lunctlon  returns  tr-je  11  a  lont  was  eriosen,  else  false  If  the  Cancel 
huttnn  is  pres5Bti  In  the  dialog.    If  a  font  Is  chosen,  Its  FontTD  inlcrmatlon 
Is  returned  in  the  qlabal  variable  DesiredFont .     In  addition,  the 
globfli  myReply .  fl  lendiAe  contains  a  string  ^hlch  is  the  font's  file  name. 

Becauae  the  call  to  Chocsernnt  actually  changes  the  fent  of  the  current 
port,  v(e  must  rtrst  save  the  current  port  and  open  a  duniny  one  do  that 
sur  current  port  is  not  affectad,] 

var  thaFont  :  FontlD; 

dyswy  !  Integer; 

trapPort  :  GrafEortPtr; 

tntpPortREC  ;  GrafEort; 

fairfJame  :  St  r  25-5,- 

begln      (of  DoChooseFontI 
tmpport  Getport; 

OpenPort   (BtmpPortBec} f  [save  nurrant  port  and  open  new  one] 

theFont  ;-  ChoosaFont  (DeilredFont, 0) ;     (Do  standard  dialog  box] 

if  longint  {theFont)  -  0  then  fCancal  was  chosen) 

DsChooseFont  false 
else  begin 

DealredFont       theFont;  ll'pdate  global  DeslredFont) 

dumny       GetFamlnfo  (Desl  red  Font.  fawHnm,  EattiNania)  ; 
nyReply. filename  :- 
concat  (fantUamftr 
I 

IntTnStrlnq  (DesitedTont . f ontSize) j ; 
DoChooeeFont  true; 

end; 

closeport  (ttmpPortMc) ; 

SetFort   (txnpPDrt)  ;  {Reatoxe  ciirrent  port] 

end;        {of  DaChooseFont ) 


procBdura  DoSetMono; 

[This  procedure  flips  the  flag  Indicating  whether  we  are  currently 
displaying  a  font  In  mono-spacing  or  not,  and  updataa  the 
font  menu  item  accordingly. } 

begin       [uf  DgSetMonol 
If  isMonoFont  then 

SetHIten  {HonoStr, Hanottefi) 

else 

SetMItera  (ProStr,HonoItem)  r 
IsMonoFonC  :-  not  IsKonoFont; 
end;         [of  DuSetHonol 


procedure:  SholKpont  {CheFontlD:  PontID;  LsHono:  bsoledn) ; 


vai  fontlnfo      :  FantlnfotteDord; 

currHaiglit  :  Integer; 

:  integer; 

theCh  :  Integer; 

curtpt         :  Point; 

fantStr        :  StrZS5; 

begln      I  of  Showront I 

InstallFont  (theFontlD, □) ; 
GetFontlnfo   (fantlnftij ; 

currHelght  fontlrfo, ascent  +  fontlnfo .deaeent  ■»■  fontlnfo, leading; 
1  :-  GetFamlnfo  (theFontlD.  EamNum,  fontStr)  ; 

fontstr  !-  concat:  ((antstr, '   ' ,  IfiCToStrlng  (theFontJD.Ioritslzen  ; 

1    :-  GetFnrtFIaqs; 
if  isMonO'  than 

i  :-  HltOT     (1,50001)  (Sat  bottsn  bltl 

el£e 

1  :-  Bit  And  {1,SC000|,-  (Clur  bottsm  bit  I 

SstFontFlags  (li ; 

HoveTo  IS,  curr Height ) ; 

Drawstring  [fontstrjf 

MoveTo  (b, currMaight  •  3) ; 

CirawString  I  'The  c;ulclc  brown  fox  junrps  over  the  lazy  dog. ' ) ; 

MoveTo  (5, currHeight  *  4) ; 

DfawStcln^  I 'She  sells  sea  shells  down  by  the  sea  shore.'); 

HoveTo  (5,  currHeight  •  5J ; 

for  1  !-  0  to  7  do  begin 
GetPan  (ciurrPtJ; 

MoveTo  (SiCurrPt.v  +  currHalght) ; 

tr*Ch  i-  J  •  32; 

for  It       1  to  32  do  begin 

fontstr  (jl    :-  elir  (theCh]  ; 

Inc  (thech) ; 

end? 

tontStr  [01   :-  chr  (32); 
Qraw^tTlng  (fontstr)  f 

end; 

endf        iot  3howFont| 


END. 
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I 


PRINT.PAS  (printing) 


OHIT  Print; 

IH  

I 


HoctgeFndge :    An  example  Apple  IIGS  Desiitcip  ai^licatlon 

Written  by  the  Apple  I ICS  Developnent  Team 
Trans J at Ed  to  THL  Pascal  by  TML  Syatems,  Inc. 

Copyright    (c)  1996-87  by  Apple  Cnnputer,  Inc, 
mi  Slights  Reserved 


Pascal  UNIT  'PRINT.PAS"  :  Wthdow  contant  printing  routines 


1NTE!(FACE 


asEs 


HPIntlEata, 
HPInttPFEc, 
HPIntfPdoa, 


(Hodg»Podga  Apple  IIGS  Twlboj;  Inte^ftace  Units) 


Qlobals, 
Dialog, 
Font, 
Paint f 


(XodigePodge  Code  Units) 


prDCEdure  DoChooBErltejrif 

pEQcedufe  DnSetupIteBi; 

procedure  DoFrlntlt^; 

procedure  SetLTpDefault ; 


[Show  st^ndaird  chooser  dialog  to  salsct  cptisns) 
[Show  standard  paga  setup  dialog  to  sel  options) 
(Print  contents  pf  current  vrlndnu  to  printer  ) 
(Create  and  Initialize  ItlPrlnt  record  ) 


ItS'IfHENTATIOK 


war  prlntHndl! 


FrHAcKndl; 


(Erivate  print  record  handle  for  Print  Manager] 


procedure  Dochoosertcem; 

[Display  the  chooser  Dialog  fot  Eh^  user  to  select  whicn  printer  and 
printer  connsotion  to  use. } 

var  dumty:  boolean; 

begin      (of  poChooserltEtn ) 

dumny  frChooser? 
anil;        (of  DoChooserltem) 


PRINT.PAS  (printing) 
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procedure  DoPrlntltam; 

iFrlnt  the  contents  of  tho  ita^t  window  to  the  selected  pi-lnter.} 

var    prJort        ;  GrafPoiaPtr; 
thewindow  :  CrafPortPtr; 

proeedure  Dranr[ip«:ndow  (theWJrvdow:  GrafPortptrl 

'rJ^n/fi*'"''^  procedure  ieCewl.es  «h^t  type  cf  «infte«  theWindo-  is 
cans  the  appropriate  procedure  to  draw  Its  contencs  to  th4!  current 
wnicn  is  now  the  printer  port  created  in  CoPrintltem. i 

var  myDataHandlej  WindDataM; 

bagifi      (of  DraHTopWlndotf) 

rayDat  a  Handle  :-  WlndDataH  (GetWRefCon  (cheWindiwn  • 
Hlth  [nyDataHandle'"  do 
If  Flag  ^  D  then 
Paint It  (plct) 

elae 

ShnwFont  (thoFont,  isMono) ; 
end?       (of  DravTopwindow] 

tJegln      (or  CtoPrirtltan) 

theWIndow  :-  Front window; 
i-E  thewlndow  <>  nil  ttien 

If  PrJobOialog  (ptlntHndl)  then  bagin 
WaltCuzEOr; 

prPorc  J-  PrppenDoc  (printHndl,nil)  ; 
PfOpanPage  (prPOirt,  nil  I  ; 

DrauTopWlridow  (theWindow) ; 

PrClosaPaga  (prPortl ; 

PrcloseDoc  (prPort) ; 

PrPlcFlie  (prlntHndl,nll,iill); 
tn It Cursor; 

end; 

end;        [of  DoPrlntlteoi) 
procedure  DoSetupltan; 

var  dunny:  boolean; 

be^ln      lot  DoseLupltem] 

donmy       PrStlDialo,  (printMndl) ; 
and;        (of  DaSetupItemf 

procedure  SetUpOefault,- 

{Create  and  Initialise  a  THPrlnt  record  whlcn  Is  required  for  all 
Pointing  operations,  t  ^ 

i^gtn      (of  SetUpDefault t 

piSntHndl  :-  PrReeHndl  (Newflandle  (no, 
rii'Heiiiorylll, 

attrNocross  +  attrLocltad, 
Ptr  (OK); 

PtDBfault  (printHndlJ. ; 
enrif        (of  £atUpDefault( 
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PAINT. PAS  (pictures  and  files) 


UNIT  Paint; 


Hodgepodge:    Jln  «xa]i^ile  Apple  IICS  Desktop  apEslleatlon 

HrLcten  by  the  AppHe  IIGS  Development  Team 
Translated  to  TML  Pascal  by  TML  Systems,  Inc. 

Copyright  (c)  lSBfi-a7  by  I^ple  Ccmiputer,  Inc. 
All  Rights  Reserved. 


faecal  UNIT  "PAINT, PftS"  :  Bitmapped  picture  loai/ssvs  and  i^rlndoiif  dxawlng  I 


INTERFACE 
nSES 

HPIbtfOata,  [Hodgepodge  Apple  TIGS  ToalbOK  Interface  Dtiltfi| 

HPIntiProc, 

HPlntfPdoE, 

Globals,  (Hodoep&dqe  Coda  Unltaj 

Dialog? 


lunctlsn    AakUser  :  boolean; 
procedure  Dafaveltenif  (If  paint 

proced ure  PalnL; 

procedure  Pelntit  (pictj  Handle); 


{Load  a  new  picture  tiani  dlslil 
window  In  front,  do  std  File  dialog  t  save! 

(Draw  picture  window  contents! 
(Do  Paint's  dirty  work) 


IMPLEMEHTAriON 


[SDBfProc  I 

tunctlon  QpenFllter  (DlrEntry  :  longlntr  !  Intagerf 

[Filter  function  called  by  the  Standard  File  CperBtlnna'  SFGetPlle 
dialog  to  determlrs  whether  a  fllenaiM  should  be  dlraned  or  noE.I 

type 

BytaPtr  ■  *bytef 
var 

flleTypePtr  :  Byteptr; 

begin      {of  DpanFlltsr} 

fileTypePtr       Pointer  (DlrEntry  +  510); 

If  <EltA{ID(Flle'IVp*^'tr"f$OOFF)  -  $Clj  then  (  Unpacked  Plcturo  File  type  i 
OpenFllter  :-  2 

else 

OpenFllter  1; 
end;        (of  CpenF liter] 


PAINT,  PAS  (pictures  and  files) 
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function  AskUsejf  :  boolean; 

var  ourTypeList  :  rypelistptr; 


function    LoadOne  :  baolear; 

(Private  procadure  which  actually  loads  a  ftcture  from  dlsltl 

ffar  openBlli  :  OpenR^c; 
TfiadBl!;  :  FilElORae; 

begin      [Of  LoadOjje) 
LoadOne  falae; 

WaitCuraor; 

PictHndl        NevrKandle  (SBDOO, 

KyHemgry ID, 

if  iBToolErroi:  thor 
EKit; 

HLoek  (PletHndlJ  ,- 

opBn&lJt^openPathrjajHB  t-  SmyHeply .  fLllpathnalIl■; 
QpenBlk,i^!Burffl^         :-  nllf 
OPEN  (openBlk}; 
If  ChBoJtDiaicError  (27 i  then 
Exlt; 

laadBlfe.dataBLiffer  Plctstndl*,- 
readBlk.reqBestcount  :-  saooo; 
readBik.fUBRefNim  Dpenailt.openftflfimm; 
READ  IreadBi):); 
If  CheckDlskError  (2S)  than 
Exit; 

CLOSE  (MadBlk); 
Htrniock    tPictHndl)  ; 

LoadOne  :-  truej 
snd;        {of  LoadOna) 


tse^iin      I  of  AskCTfler] 

SFGetPlle  (20, 
20, 

'Load  Which  picture t 

S'i^penrilter, 

Mil, 

MyRepJy) ; 

AskUser  :-  false; 
If  myStaply.good  then 
If  LoadOne  then 

AskUaor  true; 
end;        (of  hsiiuaerl 
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procedure  Do-SavElteui; 

[This  precadure  Is  called  to,  ssvb  the  coiitehtE  of  a  "PalEU-  windov* 
to  s  disk  file.    NOTE!    This  routine  Is  ONLY  called  when  a  -Palnt- 
iflncta>i  Is  In  front  due  to  e^abli ng/dlsabl Inq  the  mEnu  Items.  I 


Tsr  tfleWlndow;        GrafFortEtr ; 
inyDataHandLe;  WlrdDataH; 
1:  integer; 


procBdure  saweQne  (plct :  Handle) ; 

[Private  procedure  which  actually  does  the  picture  savel 


vsf  dastroyBlX 
createBllt 
apenBil]( 
wrlteBlIt 


FathNamenec; 
File Reef 
openEiec; 
FlieloRecr 


begin      (of  SaveOna! 

destroyBik, pathname  :- 
DESTROY  (dest  royBl  ft  1  ; 

create  Bl  It .  pat  hname 
crepteBlIt .  f  decess 
createBllc.  filEType 
createBlk.aUJSfype 
createBlk . EtorageTypo 
creataBlk. craateDate 
crea  teB  1  It ,  e  rea  teT  lire 
CREAtE  ( creat  eB  1  It  1  ; 
ir  ChockOisltError  (25) 
EJtttf 

openBllt.openPathnaiiie  :■ 
DpenBl)!.  loBuffer  ;■ 
QPEM  (epenBLK); 


graVR8[3ly .  fullpathname; 


-  jmySepljf.  full  pathname; 
- 

-  SClf 
- 

-  i; 

-  Uf 

-  0; 


then 


SmyReply- fullpathname; 
nil; 


(DHtWR,  see  PraDOSie  docst 
(Dnpac'KEd  file) 
( -nothirtg- 1 
(seedling  {lUI 


wrlteBlk.dataBuf far 
wr  IteB  1  Ic  -  requE  st  Count 
urtteBlJt  .f  lleRerNum 
WRITE  (urltaalkl; 
If  CheclcDtsl(E.rr!>r  (16)  then 
Exit; 

CLOSE  (HrlteBlIt); 
end;        [of  SaveOneJ 


-  pict"; 

-  S80[50; 

-  opatiBlk.opanftelNim; 


begin      lof  DoSavaltom] 

theWlndow  FrontWlndow; 

inyDataHandle  WlhdDataH  (GetWBefCon  (theWlndotf) )  ; 
sFPutFlle  (20, 

'Save  Mhleh  picture:*, 
myDat  aHandlB~~.Naine, 
15, 

sryReply) ; 

If  myE(*ply .qo&d  then  begin 
WaltCursor; 

SflveOiiE  (niyDataHandlc'"*.plctli ; 
with  mylJataHaridle^''  da  Segln 

(Change  name  of  correct  menu  item; [ 

Hatne  !-  myReply. Ill ename; 


PAIIMTPAS  (pictures  and  files) 


ManoStr  concat 

fiiyRepJy,  filename, 
■\M', 

Inttostring  (MenuID), 
■\0,') ; 

for  1        FlrEtwlnd  to  LastHlnd  do 

If  WlndotfLlst  [Ij  .  thoWlncioH  then 
leave;     lEnle  loop] 
^^^S^Mll^  (Hentiat.:,Fir5tWlMIt«™  +  i,  ; 

Cialc*tenusls«  (O.O.wlndmsMenulDl  ; 
InitCursorf 

end; 

»fKl,-        (of  DoSaweltasf 
prooadure  Paint; 

var  tmpport  :  Graf Port Ptr; 

niySataHaJidl*  ,■  HlndDacaH; 

iHigln       [of  Paint) 

tmpPort  :_  Get  Port; 

PalntlE  (ray[]iataHaiMile-''.plet);  ituilm, 
end;        f of  paint | 

procedure  Paint  it  (picc;  Handls); 

(Procedure  tc  a^uatly  dr,M  tU.  picture  in  „«»ry  to  th«  .l„do.., 

var  srcLoc    :  Loelnfo; 
srcRect  :  Ract; 

*»gin       !(if  Paint  It  I 
Hlcck  {pietl  ; 


with  fircLoc  do  begin 
pflrtscB 
ptrToPlxTmage 
Iwltlth 


plct-; 
160; 


end; 


1^*"^*°^  (boundlHReGt, 0,0, 640,200); 

BoundsRect .  ¥l         :-  0; 


SetHEct     1 B reflect, 0, 0,  MO,  200 1  ; 
PProPort  {sreloc, 
srcReet, 

HUnLocIt  (pict) ; 
Bn*i;       (of  Palntltj 


END. 
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Appendix  G:  Hodgepodge  Source  Code;  Pascal 


GLOBALS.PAS  (global  data) 


UUTT  GlqtiaU; 

(  +  — :  

I  HcdgBPodge:    An  example  Apple  IIGS  DesXtop  sppH^^'ion 

i  written  by  the  Apple  IIGS  Development  Team 

I  Translated  to  THL  Fiscal  by  TML  Systems.  In^. 

I  Copyright   (c)  1386-87  lay  Apple  Coaiputer,  Inc. 

I  ftil  Rlqtita  ResErvEd 


Pascal  KNIT  "GLOBRLB, PAS"  :  Global  data  atruccs  and  inlt  routine  I 
 -+] 


ISTEHFACE 


USES 


HPIntfMta, 
HPlnttFroe, 
HPIil.tfPde>s,* 


[Hodgepodge  /kpple  I  ICS  Toolbox  Interface  Units} 


screenHode 


(£40  irode) 

fi4D|  X  clairp  Ishouid  correspond  to  ScreenMsde) 

4HaK  Bice  at  scan  line! 


AppIeHenuID  -  300; 

Abo.itIt«n  -  301; 

FileMenuID  -  400,- 

Openltcim  -  flOl; 

CloBBltera  -  335; 

EaveAslteir  -  403; 

choose  Pit  em  -  idb; 

PageSetltera  -  iOS; 

Printltera  -  flB7; 

Quit  Item  -  4  09; 

GdltKBiiuID  -  SDO; 

andoiten  -  iSO; 

Cutltem  -  251; 

Copylteiti  »  2S2; 

PaBLeltEm  -  iS3; 

claarltein  -  354; 

WlndowsHenuID  -  £DD; 

NoWindDUsItEiii  - 

FirstMindltam  -  3000; 

FontBManuID  -  700; 

Font  Item  -  701; 

Mono  Item  -  702; 


[For  DA'S) 


FlrstWlnd 
LaEtHind 


0; 
15; 


[FOE  DA'St 
[For  DA-s> 
(For  DA'fif 
(For  DA'sJ 
[For  DA' si 


[Allocated  dynamicdliy  starting  at  2000} 


[Lower  botmd  of  HlndowList] 
[Upper  bound  of  WlndowLisc] 


GLOBALS.PAS  (global  data) 
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type 


WindDataH 
WlndOstaP 
WindDataRec 


"WlndDstaP; 

record 

Menu St r 
HenjID: 
Flag: 


Str255; 
integer ^ 
Integer; 


case  Integsr  of 


(RefCon  data  for  am  wlndpwsf 
I.., carried  along  with  krlnd  data) 


end; 


(thioFont : 
isMono  J 
(pict: 


Ealnt,  1  -  Font] 


Font IE; 
boolean)  ; 
HantJle)  ; 


MVMetnoiylD 

Done 

tttQlsZerofage 
Event 

flppleflaniiStr 

FlleHenuStr 

EdltMajiuStr 

Wtndok*lenuStr 

FontMenustr 

NoWlndStr 
MonoStr 

Prostr  : 

LaatWlndow  ; 

dunmy  ■ 

DeslredFont  : 

laMojiaFonE  ; 

rayREply  . 

PlctHndl  : 

WInctex  . 
WindoMLiat  : 


PlswtTeuip 
PlBWtltem 

Applelcon 


I  Integer; 

Hanaie; 
WmTaakRec:,- 

SLr2  5S,- 
Str255; 
Str255; 
Str255f 
Str255; 

String  Ho 
String  HO 
String  [4DJ 


fApplicatlor.  ID  aaslgned  by  Mes^^rv  Mori 
(True  whan  quitting} 

j Handle  to  Zero  page  me-nory  for  Toolsl 
(Aii  events  are  returned  here) 

1  For  creating  menus) 


1;     IMenu  Itera  string  for  -Ko  Windows...-} 


GrafPortPtr; 

intoger; 

FDjitrD,- 

boolean; 

SFftepi yRec; 

Hardle; 

Integer; 


(The  Front  Hind;.*,  la«  time  through  event 
I        >!<:  Possihl*  conipHer  bug7| 
(Indicates  current  selEcted  font| 
iflag  Indlcjtea  if  ^ano  spacing  Mleccedf 


J Count  of  number  of  windows  open) 
lliEt  oT  up  to  IS  open  wlndowal 
^rray  [f  Ir.tHind. .  iastWindl  nf  Gr^PoxtPtrr 

DialogTeiiiplate; 
IteirfTempiate; 


record 

boundsRect 
data 

end; 


Rett  ; 

array  of 
Packed  arrsy  [l. 


.16)  of  byte; 


procedure  InltGiobalsf 

PHOCEOURE  HPStuffKex  (thingPtr  )  Ptr-  s  ■  st,,.^=;.  '^"""P  variables) 

'  *  *  5tr255);  (Store  he*} 
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IMPLEMENTATIDM 


PBflcEDURE  HPStuffHex  (thlrflPtf  :  Ptr;  b  :  Str255}; 

ls!<  This  routine  will  be  Inplemcntod  In  TML  Pascal  VI. 1.     For  now, 
we  define  it  aurselveB.     StuflHeK  stores  bytes  (enpressed  as  a  string 
of  hexadecimal  digits)   Into  any  data  strutrture,  and  Is  based  on  ths; 
stutiHex  procedure  in  Haclnt&shi  QuickDraw.    Ttie  resolution  of  this 
routine  la  on  byte  boundaries.) 

var  Iterator       ;  IfiteQer; 
strl  nijTndejt  :  Integer; 

begin      fof  HPStuIfHenl 

for  Iterator        D  to  Length  (s)   -  1  do  begin 
atrinjIndeR        (Iterator  *  2)  +  1; 

thlnqptr*  ;-  HeKllnt  [StrinqPtr  (longlnt  [Usi  +  etringliulex) , I)  r 
thlngFtr       pointer  (ion^liiti  (thlnsPtrJ  +  1)  ; 

«nd; 

end;  (of  HEStuffHftK] 


procedure  InltGlnbsals; 

(Ifiltlallae  global  data  variables.  Including  the  plsWtremp  asBd  by 
ShowPleaseWa It Dialog,  tha  menu  strings  used  by  the  menu  bar  setup 
rnutlnes  In  MENU, PAS,  and  the  Apple  icon  used  by  the  "about,,," 
item  dialog  routine  in  DIM.Cn3.PAS( 

begin      (of  initGlobals) 

with  PlsWtTemp  do  begin 

Setnect  (dtBaundsEleDt,  120 ,  30, 520,  BO)  ; 

dtVislble  :-  true; 
dtHefcon  0; 

dtltemLlst  [01        pointer  {(J);  (We  will  Insert  ptjr  to  Item  here) 

dtltojiiLlst  [1]        nil;  (»ull-tennlnated| 


AppleHenuStr  :"  concat  ( 
Fll«>Henu5tc         concat  ( 


EiltManusti:    !-  cnncat  i 


WindowManuStr 
FontHenuStr 


conE»t  I 
concat 


--About  HodgePod5o...\ff301\0', 

— \n303d\0.  ■!  ; 

»    File  \WOO\.Q', 

—Open . . . \m01 'Oo\D  ■ , 

— C1osbVM255D\0', 

—Save  As. . .  \N1D3D\0' , 

—Choose  Printer..  .\mD5\CI' , 

—Page  Setup.  .  .\K406D\0' , 

--print.. .\N407«ppD\O', 

— VN40BD\0', 

— Oult\N40S'Q(i\0.  '1; 

»    Edit  \N5nflD\(J', 

~Undo\N!5C3''Z3\0', 

—  ^K501D\t3', 
-^ut\N251*)fji\Ci ' , 
-^Qpy\N?52*Cc\0  ■ , 
— PaBtE\MJ53*W\D  ■ , 
— Clear\»i3b4\0. ')  ; 

»    Window  \N6QODN0', 

—  No  WindoWB  AliocatedVHfifllDSO,  ■  ) 
'»    Fonts  \Ci700\a-, 
—Display  Font. .  ,\pr7(31'Ff\a', 
—Display  Font  as  Tlono-spacedNH70Z*KA\0, 


); 


LastHlndcw 


nil? 
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HcrWlndstr 


-^Ha  ttlndoue  Allocatied\N£aiD\0, 


MbnoStr  '""DlspLay  Font  as  Msno-spaced'; 

Pro St r  "-Display  Font  as  PtopDrtional' 

laMsncFont.  false; 

with  DaalredPorit  do  begin 


fginNtim 
fohtstylE 
font  Size 

end; 

WlncSflx  0; 

SetRect 
HPStuffHex 
HFStuffHex 
KPStuffHex 
HPStiiffHox 
HPStuffHex 
HPStuftHex 
HPStuffHex 
HPStuffHex 
H?SEu£IHex 

HPStuffHex 
HESCUtrHeX 
HSStuffHBK 
HEStuffHex 
NfStuffHex 
HPStuffHex 
HPStuffHex 
HPStuffHex 
HPStuItHex 
HPStufffleX 
HFStuftHex 
HP  Stuff Hex 
HPStuf fHex 
KPStiif  IHeJc 
HPStuf fHex 
HFStuffHen 
HPStjf fHEX 
HFStjf fHEK 
HPStuffHen 
HPStuf (Hex 
HPStuf f Her 
HPStuf  fHex 
HPStuf  fHelt 
HE Stuff Hex 


-  D; 

-  B; 


IfippI elcon. bounds Beet 
[JApplalcon.data [1 ] 
( I^Appl  el  con ,  dat  a  1 2 1 
(9AppleIcQn.dat a [3] 
(iJApplelcon.data  [4] 
(9/LppleIcQn.  data!  5 1 
l@ApplEjcor,teta.[61 
(SApplelcon. data [ 7 1 
( SAppl el con . dat a [ 8 1 
(lAppl el dtih ,  da t a  [ 9 ] 
(iAppielcnn.dataLlCl 
ISAppleIcsn.data[ll 
( SApplel can . da c a  1 1 J 
( lApplel can , da  ta { 1 3 
(EAppl«Iccyn,data  [14 
tIApplelcon.data [1 5 
C ! Applsl C9n . da  t  a [ 1 E 
(9 ApplflIcon.dat a [17 
{^Applelcon.data [13 
(UApplEjcEsn.d^ta  [19 
[UApplElcor.data [10 
[SApplelcon.data [21 
[ 9 Appl el con . dat  a [ 2  2 
((JApple'Icon.data[23 
(SApplBlcon-dsta [24 
($AppleIcon.daca[2S 
{ i Appl elcon.datd[26 
iSApplelcnn . dsts [27 
I  i Appl el con . dat  a [ 2  8 
{eAppleIco;i.data[2» 
(6ApplelePT5.data[30 
(EApplelcon .dac  a [31 
( SAppl e I con . da ta ( 32 
(eAppleTcon.datalSl 
(EApplelcon  .data  [34 


\Ho  mlndovs  open  yet) 
0,t),6'l,31)  ; 

000  Q  0  00  0  OOQQ  QOOO  Q  00  0  OOOOQ  QOa  Q  OOH  < 
' OFFFFFFFrFFFF  FFFF  FFFFFFFF  F  FFFFFO ' 
>  OFOO  0  00  0  00f>0  0  0  DO  0  000  0  0  D  00  D  DO  D  QFO ' 
■ OFOFF  FFFFF  FFF  F  FFFFFFFF  F  FFF  FFFO  FO ' 
■ OFOFF  FFFFFF  FF  F  FFFFFFFe  S  FFF  FFFO  F  0 ' 
'DFDFFFFFFFFFFFFFFrFaBBBFFFFfFOFD' 
' 0  F  OFFFFFFF  FFFFFFFrBBBBB  FFFFFFO  FD ' 
'OFOFFFFFFFFFrFFFFSBSBaFFFFFFFOFD' 
' 0  FDFFFFFFF  F  FFFFF88  9  B  H  F  FFFFFFO F  0 ■ 
' 0  FOFFFFFFF  F  FFFFF  B  fl  B  B  BFFFFFFF  F3FD  ■ 
' 0  FOFFFF  F  FF  F  FFFFF  8  B  a  a  FFr  F  FFFF  FOFO " 
'0F0FFFFFFBBSfiFFF8BFF9fi89FFFFFt)F0' 
'0F0FFFFBB89SBaBFFFe8B888B6FrF0F0' 

'0F0FFFe9ses9eaB9se3e9aesg9aFFCiF0- 

' 0  FO  F  Fee  eeee  eeeeeeee  e  eeeee  F  FFF  OFO ' 
'CFOFFeeeeeeeeeeeaeeeeeeeFFFFFOFO' 
'  OFO  FPeo  c  ai^eeee^o  eoccoooFF  F  FFFOPQ ' 
'OFaFF66fi66S6666666S6666FFFFFF0FO* 
*OFOFF6t«6666666*6«66566FFFFFF0FO< 
'OFClFF666fi666666S6fi6666«FFFFFF0FO> 
■{)FOFF44444  4444  4^444  4  444  4FFFFFCIF0  ■ 
■ DFCFF44444 4 44444444 4  444 44FrFFaFD ■ 
'DF0FFF4444 4 44444444 4 444 4444FFaFD> 
'  0FOFFF&b55555555  5  55555555  55FF(}F0  ■ 
'0FDFFF555S55SS555 55555555 5 SFFOFO- 

■  0FDFFFF55S555S55555553S55:5FFFOFD  ■ 
■ OFDFFFFlllllllll 1111 11111 IFFFOFO ■ 
'OFDFFFFFlllllllllllllllllFFFFOFO- 

■  0  F  OFFFFFFl 1 1 1 1 IFFFl 1 111 IFFFF  F  DFD ■ 
■ OFOFf FFFFFllllFFFFFllllFrFFFFOFO ■ 
■ OFOFFFFFFFFFFFFFFFFFFFFFFFFFFOFD ' 

" aFOOcaoDDQQDoaaDooooooooDOOQQDFO  ■ 

' OFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFO ■ 

'  oooooooDoaooooaooooooooocioooaooo  > 


end; 


(of  InltGlobalBl 


END, 
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Glossary 


absolute:  Characteristic  of  a  load  segment  or 
other  program  code  that  must  be  loaded  at  a 
specific  address  in  memory  and  never  moved. 
Compare  relocatjible,  position-Independent, 

absolute  addressing:  an  addfcssing  mode  in 
which  instnJClian  operands  are  interpreted  as 
literal  addresses, 

access  Cot  access  byte):  An  attribute  of  a  ProDOS 
file  that  controls  whether  the  file  may  be  read 
from,  written  to,  renamed,  or  backed  up. 

accumulator:  The  register  in  a  computer's  central 
processor  or  microprocessor  where  most 
computations  are  performed, 

activate:  To  make  active.  A  control  or  window 
may  be  activated.  Compare  enable. 

activate  event:  a  window  event  that  occurs  when  a 
window  is  made  either  active  or  inactive. 

active;  Able  to  respond  to  the  user's  mouse  or 
keyboard  actions.  Controls  and  windows  thai  are 
active  arc  displayed  differendy  from  inactive 
items. 

ADB:  See  Apple  Desktop  Bus. 

address  bus:  The  bus  that  carries  addresses  from 
the  CPU  to  components  under  its  control. 


advanced  Unker  (APW):  One  aspect  of  the  linker 
supplied  with  APW.  The  operation  of  the 
advanced  linker  is  programmable.  Compare 
standard  linker. 

alert:  A  warning  or  report  of  an  error  in  the  form 
of  an  alert  box^  a  sound  from  the  computer's 
speaker,  or  both. 

alert  box:  A  special  type  of  dialog  box  that 
appears  on  iKe  screen  to  give  a  warning  or  to 
report  an  error  message  during  use  of  an 
application. 

alert  window:  The  window  in  which  an  alert  box 
appears.  One  of  the  two  predefined  window 
formats.  Compare  document  window, 

analog  RGB:  A  type  of  color  video  consisting  of 
separate  analog  signals  from  the  red,  green,  and 
blue  color  primaries.  The  intensity  of  each 
primary  can  vary  continuously,  making  possible 
many  shades  and  lints  of  colors.  Compare  TTL 
RGB. 

Apple  Desktop  Bus  (ADB):  An  input  bus,  with  its 
own  protocol  and  electrical  characteristics,  that 
provides  a  method  of  connecting  input  devices 
such  as  keyboards  and  mouse  devices  to  personal 
computers. 

Apple  Desktop  Dus  Tool  Set:  Ihe  Apple  lIGS  tool 
set  that  facilitates  an  application's  interaction 
with  devices  connected  to  the  Apple  Desktop 
Bus. 
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Apple  key:  A  modifier  key  on  the  Apple  llGS 
keyboard,  marked  with  boLh  an  Apple  icon  and  a 
spinner,  ihe  icon  used  on  ihe  equivalent  key  on 
some  Macintosh  keyboards.  It  pterforms  the  same 
functions  as  the  Open  Apple  key  on  standard 
Apple  II  machines. 

AppIeTalk  network:  A  local  area  network 
developed  by  Apple  Computer,  Inc. 

Apple  11:  A  family  of  computers,  including  the 
original  Apple  II,  tiie  Apple  II  Plus,  tlie  Apple  He, 
the  Apple  lie,  and  the  Apple  IIGS.  Compare 
standard  Apple  II. 

Apple  Ua  A  transportable  personal  computer  in 
the  Apple  II  family,  with  a  disk  drive,  serial  ports, 
and  80-column  display  capability  built  in. 

Apple  He:  A  personal  compuEer  in  the  Apple  II 
family  with  seven  expansion  slots  and  an 
auxiliary  memory  slot  thai  allow  the  user  to 
enhance  the  computer's  capabilities  with 
peripheral  memory  and  video  enhancement 
cards, 

Apple  IIGS;  The  most  advanced  computer  in  the 
Apple  II  family.  It  features  expanded  memory, 
advanced  sound  and  graphics,  and  the  Apple 
IIGS  Toolbox  of  programming  routines. 

Apple  IIGS  Debugger:  A  65B16  machine  language 
code  debugger  for  the  Apple  IIGS  computer. 

Apple  n<a;  Programmer's  Workshop  Capw):  A 

multi language  development  environment  for 
writing  Apple  HGs  desktop  applications. 

Apple  IIGS  Toolboac;  An  extensive  set  of  routines 
that  facilitate  writing  desktop  applications  and 
provide  easy  program  access  to  many  Apple  IIGS 
hardware  and  firmware  features. 

Apple  H  Plus:  A  personal  computer  in  the  Apple 
II  fannily  with  expansion  slots  that  aJIow  the  user 
to  enhance  the  computer's  capabilities  with 
peripheral  cards. 


application;  A  stand-alone  program  that 
performs  a  specific  function,  such  as  word- 
processing,  drawing,  or  telecommunications. 
Compare,  for  example,  desk  accessory  or  device 
di^ver, 

appUcaUon-defined  event:  Any  of  four  types  of 
events  available  for  applications  to  define  and 
respond  to  as  desired.  M 

application  prefix!  The  ProDOS  16  prefix  numbw' 

1  / ,  It  specifies  the  directory  of  the  currently 
running  application. 

application  window:  A  window  in  which  an 
application's  document  appears.  ^ 

APW:  Sec  Apple  IIGS  Progranan%er*s  Workshop. 

APW  Assembler:  The  65816  assembly-language 
assembler  provided  with  the  Apple  liGS  j 
Programmer's  Workshop.  ■ 

APW  C  Compiler:  The  C-language  compiler 
provided  with  the  Apple  IIGS  Programmer's 

Workshop, 

AI*W  EdUor:  The  program  within  the  Apple  IIGS 
Programmer's  Workshop  that  allows  you  to  enter, 
modify,  and  save  source  files  for  all  APW  J 
languages, 

APW  Linker:  The  linker  supplied  widi  the 
Apple  IIGS  Programmer's  Workshop. 

APW  SheU:  The  programming  environment  of 
the  Apple  IIGS  Programmer's  Workshop — it 
provides  facilities  for  file  manipulation  and 
program  execution,  and  supports  shell 
applications.  i 

APW  utility  program:  Any  of  various  Shell 
applications  supplied  with  the  Apple  IIGS 
Programmer's  Workshop  that  function  as  APW 
Shell  commands. 

arc:  A  portion  of  an  oval;  one  of  the  fundamental 
shapes  drawn  by  QuickDraw  [1. 

A  reglsten  See  accumulator. 
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ascent;  In  a  foni,  ihe  distance  beiween  the  base 
line  and  the  ascent  tine, 

ascent  line;  A  horizontal  line  that  coincides  with 
the  tops  of  the  tallest  characters  in  a  font.  See 
also  base  line,  descent  line. 

ASOl:  Acronym  for  American  Startdard  Code  for 
In/ormaiion  Interchange,  pronounced  "ASK-ee." 
A  code  in  which  the  numbers  from  0  to  127  stand 
for  text  characters.  ASCII  code  is  used  to 
represent  text  inside  a  computer  and  to  transmit 
text  between  computers  or  between  a  computer 
and  a  peripheral  device. 

assembler;  A  language  translator  that  converis  a 
program  written  in  assembly  language  into  an 
equivalent  program  in  machine  language.  The 
opposite  of  a  disassembler. 

attributes  word;  Determines  how  memory  blocks 
are  allocated  and  maintained.  Most  of  the 
attributes  are  defined  at  allocation  time  and  can't 
be  changed  after  that;  other  attributes  can  be 
modified  after  allocation. 

auto-key:  A  keyboard  feature  and  an  event  type,  in 
which  a  key  being  held  down  continuously  is 
interpreted  as  a  rapid  series  of  identical 
keystrokes, 

auxID:  A  subfield  of  the  User  ID,  An  application 
may  place  any  value  it  wishes  into  the  auxID 
field 

auxiliary  type:  A  secondary  classification  of 
ProDOS  files.  A  file's  auxiliary  lype  field  may 
contain  information  of  use  to  the  applications 
that  read  it.  Compare  file  type. 

background:  The  pixels  within  a  character  or 
other  screen  object  that  are  not  part  of  the 
object  itself. 

background  colon.  The  color  of  background 
pixels  in  text,  by  default  it  is  black. 

background  pattern:  The  pattern  QuickDraw  II 
uses  to  erase  objects  on  the  screen. 


background  pixels:  In  a  character  image,  the 
pixels  that  are  not  part  of  the  character  itself 

background  procedure:  A  procedure  run  by  the 
Print  Manager  whenever  the  Print  Manager  ha.s 
directed  output  to  the  printer  and  is  wailing  for 
the  printer  to  finish. 

backup  bit:  A  bit  in  a  file's  access  byte  that  tells 
backup  programs  whether  the  file  has  been 
altered  since  the  last  time  ii  was  backed  up. 

bank;  A  64K  C65,536-byte)  portion  of  the  Apple 
IIGS  internal  memory.  An  individual  bank  is 
specified  by  the  value  of  the  65816 
microprocessor's  bank  register. 

bank-swltclied  memory:  On  Apple  U  computers, 
the  part  of  language  card  memory  in  which  two 
4K  portions  of  memory  share  the  same  address 
range  (SDOOO  to  $DFFF). 

bank  $00:  The  first  bank  of  memory  in  the  Apple 
IIGS.  In  emulation  mode,  it  is  equivalent  to  main 
memory  in  an  Apple  He  or  Apple  lie  computer, 

base  line:  A  horizontal  line  that  coincides  with 
the  bottom  of  the  main  body  of  each  character 
in  a  font.  Character  descenders  extend  below  the 
base  line. 

BA^IC:  Acronym  for  Beginners  All-purpose 
Symbolic  InsirucHon  Code.  DASIC  is  a  high-level 
programming  language  designed  to  be  easy  to 
learn.  Applesoft  BASIC  is  built  into  the  Apple 
IIGS  firmware. 

batch:  A  mode  of  executing  a  computer  program 
in  which  all  code  and  data  required  by  the 
program  are  loaded  into  the  computer  at  the 
beginning,  the  program  is  run,  and  all  results  are 
output  at  llie  end.  Batch  mode  is  non-interactive, 

binary  file;  (1)  A  file  whose  data  is  to  be 
interpreted  in  binary  form.  Machine-language 
programs  and  pictures  are  stored  in  binary  files. 
Compare  text  file.  (2)  A  file  in  binary  file  format, 
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binary  file  formatj  The  ProDOS  8  loadable  file 
fomat,  consisLing  of  one  absolute  memory 
image  along  with  its  destination  address.  A  file  in 
binary  file  format  has  ProDOS  file  type  $06  and 
is  referred  to  as  a  BIN  file.  I'he  System  Loader 
cannot  load  BIN  files. 

bit;  A  contraction  of  birmry  digit,  ihe  smallest 
representation  of  data  in  a  digital  computer. 

bit  plane:  A  method  of  representing  images  in 
computer  memory.  In  a  bit  plane,  consecutive 
bits  in  memory  specify  adjacent  pixels  in  the 
image;  if  more  than  one  bit  is  required  to 
completely  specify  the  state  of  a  pixel,  more  than 
one  bit  plane  is  used  for  the  image.  Compare 
tlnmfcy  pixels, 

block;  (I)  A  unit  of  data  storage  or  transfer, 
typically  512  bytes.  (2)  A  contiguous  region  of 
computer  memory  of  arbitrary  size,  allocated  by 
the  Memory  Manager.  Also  called  a  memory 
block. 

block  device:  A  device  that  transfers  data  to  or 
from  a  computer  in  multiples  of  one  block  (512 
bytes)  of  characters  at  a  time.  Disk  drives  are 
block  devices.  Also  called  block  I/O  device. 

Boolean  logic:  A  mathematical  system  in  which 
every  expression  evaluates  to  one  of  two  values, 
usually  referred  to  as  TRUE  or  FALSE. 

Boolean  variable:  A  variable  that  can  have  one 
of  two  values,  usually  referred  to  as  TRUE  or 
FALSE. 

boot  prefix:  The  ProDOS  l6  prefix  number  */.  It 
specifies  the  name  of  the  volume  from  which  the 
currently  running  version  of  ProDOS  l6  was 
started  up. 

boundary  rectangle:  A  rectangle,  defined  as  part 
of  a  QuickDraw  II  Loclnfo  record,  that  encloses 
the  active  area  of  the  pixel  image  and  imposes  a 
coordinate  system  on  il.  Its  upper-left  corner  is 
always  aligned  on  the  first  pixel  in  the  pixel  map, 

boundsRect:  The  GrafPon  field  that  defines  the 
port's  boundary  rectangle. 


breakpoint;  A  machine-language  instruction  in  a 
program  that  causes  execution  to  halt, 

buffer;  A  holding  area  of  the  computer's  memory 
where  information  can  be  stored  by  one 
program  or  device  and  then  read,  perhaps  at  a 
different  rate,  by  another;  for  example,  a  print 
buffer. 

Busy  flag:  A  feature  that  informs  the  Scheduler 
whether  a  currently  needed  resource  is  busy  or 
available. 

button:  (1)  A  pushbutton-like  image  in  a  dialog 
box  where  the  user  clicks  to  designate,  confirm, 
or  cancel  an  action.  Compare  radio  button, 
check  box,  (2)  A  button  on  a  mouse  or  other 
pointing  device.  ^ 

byte;  A  unit  of  information  consisting  of  eight 
bits.  A  byte  can  have  any  value  between  0  and 
255,  which  may  represent  an  instruction,  letter, 
number,  punctuation  mark,  or  other  character. 
See  also  bit,  kilobyte,  meg^yte. 

C:  A  high-level  progtamming  language.  One  of 
the  languages  available  for  the  Apple  IIGS  j 
Programmer's  Workshop. 

canceL'  To  stop  an  operation,  such  as  the  setting 
of  page-setup  values  in  a  dialog  box,  without 
saving  any  results  produced  up  to  that  point. 

Cancel;  One  of  two  predefined  item  ID  numbers 
for  dialog  box  buttons  (Cancel  =  2).  Compare 
OK, 


card:  See  peripheral  card. 


caret:  A  symbol  that  indicates  where  something 
should  or  will  be  inserted  in  text.  On  the  screen  it 
designates  the  insertion  point,  and  is  usually  a 
vertical  bar  ( I ), 

carry  flag:  A  status  bis  in  the  microprocessor  " 
indicating  whether  an  accumulator  calculation 
has  resulted  in  a  carry  out  of  the  register. 

CDA;  See  classic  desk  accessory. 

c  fLifi;  See  carry  Oag. 
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character:  Any  symbol  that  has  a  widely 
understood  meaning  and  thus  can  convey 
Information.  Same  characters — such  as  letters, 
numbers,  and  punctuation — can  be  displayed  on 
the  monitor  screen  and  primed  on  a  printer. 
Most  characters  are  represented  in  the  computer 
as  one -byte  values. 

character  device:  A  device  that  transfers  data  to 
1    or  from  a  computer  as  a  stream  of  individual 
j    characters.  Keyboards  and  printers  are  character 

devices. 

character  image;  An  arrangement  of  bits  that 
defines  a  character  in  a  font. 

character  origin:  The  point  on  the  base  line  used 
as  a  reference  location  for  drawing  a  character. 

character  width,-  T'he  number  of  pixels  the  pen 
position  is  to  be  advanced  after  the  character  is 
drawn, 

check  box:  A  small  box  associated  with  an  option 
in  a  dialog  box.  When  the  user  clicks  the  check 
box,  tliat  may  change  the  option  or  affect  related 
options. 

Choose  Printer:  A  part  of  the  Print  Manager  that 
lets  the  user  select  a  printer  or  port  for  printing. 

chunklness:  The  number  of  bits  required  to 
describe  the  state  of  a  pixel  in  a  pixel  image. 

chunky  pixels:  A  method  of  representing  images 
in  computer  memory.  In  chunky  pixel 
organization,  a  number  of  consecutive  bits  in 
memory  combine  to  specify  the  state  of  a  single 
pixel  in  the  image.  Consecutive  groups  of  bits 
(the  size  of  the  group  is  equal  to  the  image's 
chunklness)  define  adjacent  pixels  in  the  image. 
Compare  bit  plane. 

damp  values;  The  x-  and  y-limits,  in  terms  of 
pixels,  on  cursor  position  controlled  by  mouse 
movement. 


classic  desk  accessory  (CD A):  Desk  accessories 
designed  to  execute  in  a  non-desktop,  non-event- 
based  environment.  Compare  new  desk 
accessory. 

click:  To  position  the  pointer  on  something,  and 
then  to  press  and  quickly  release  the  button  on 
the  mouse  or  other  pointing  device. 

clip:  To  restrict  drawing  to  within  a  particular 
boundary;  any  drawing  attempted  outside  that 
boundary  does  aot  occur. 

Clipboard:  'the  holding  place  for  what  the  user 
last  cut  or  copied;  a  buffer  area  in  memory. 
Information  on  the  Clipboard  can  be  inserted 
(pasted)  into  documents.  In  memory,  the 
contents  of  the  Clipboard  are  called  the  desk 
scrap. 

clipping  region:  The  region  to  which  an 
application  limits  drawing  in  a  GrafPort. 

clock:  (1)  The  timing  circuit  that  controls 
execution  of  a  microprocessor.  Also  called  the 
system  clock.  (2)  An  integrated  circuit,  often  with 
battery-backup  memory,  that  gives  the  current 
date  and  time.  Also  called  the  clock-calendar, 

clock  speed)  The  frequency  of  the  system  clock 
signal  in  megahertz, 

close  box:  The  small  white  box  on  the  left  side  of 
tlie  title  bar  of  an  active  window.  Clicking  it 
doses  the  window. 

CMOS:  Abbreviation  for  complementary  meial- 
oxide  semiconductor,  one  of  several  methods  of 
making  integrated  circuits  out  of  silicon.  CMOS 
devices  are  characterized  by  their  low  power 
consumption.  CMOS  techniques  are  derived 
from  MOS  techniques. 

color  table:  One  of  16  possible  lookup  tables  in 
Apple  IIGS  memory,  that  lists  the  available  color 
values  for  a  scan  line. 
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commaiid  line:  CI)  In  APW,  the  line  of  lext  with 
which  the  user  invokes  a  procedure  or  function 
or  executes  a  program.  The  command  line  often 
includes  both  the  name  of  the  function  to 
execute  and  a  list  of  parameters  to  be  passed  to 
the  function.  (2)  The  line  on  the  screen  on  which 
a  command  is  entered. 

command-Uae  Interface;  The  type  of  inierrace 
between  user  and  prograni  in  which  information 
is  passed  in  a  command  line. 

compaction:  The  rearrangement  of  allocated 
blocks  in  memory  to  open  up  larger  contiguous 
areas  of  free  space. 

compiler;  A  program  that  produces  object  files 
(containing  machine-language  code)  from  source 
files  written  in  a  high-level  language  such  as  C. 
Compare  assembler. 

content  region:  The  area  in  a  window  in  which  an 
application  presents  information  to  the  user. 

control:  An  object  in  a  window  with  which  the 
user,  u.sing  the  mouse,  can  cause  instant  action 
with  visible  results  or  change  settings  to  modify  a 
future  action. 

controlling  program;  A  program  that  loads  and 
runs  other  programs,  without  iLself  leaving 
memory.  A  controlling  program  is  responsible 
for  shutting  down  its  subprograms  and  freeing 
their  memory  space  when  they  are  finished.  A 
shell,  for  example,  is  a  controlling  program. 

Control  Manager:  The  Apple  IIGS  tool  set  that 
manages  controls. 

Control  Panel:  A  desk  accessory  that  lets  the  user 
change  certain  system  parameters,  such  as 
speaker  volume,  display  colors,  and  configuration 
of  slots  and  ports, 

coordinate  plane:  A  two-dimensional  grid 
defined  by  QuickDraw  U.  All  drawing  commands 
are  located  in  terms  of  coordinates  on  the  grid. 


coordinates:  X-Y  locations  on  the  QuickDraw  il 
coordinate  plane.  Most  QuickDraw  routines 
accept  and  return  coordinates  in  the  order  (Y,X), 

copy:  To  duplicate  something  by  selecting  it  and 
choosing  Copy  from  the  Edit  menu.  A  copy  of 
the  selected  portion  is  placed  on  the  Clipboard, 
without  affecting  the  original  selection. 

creation  date:  An  attribute  of  a  ProDOS  file;  it 
specifies  the  date  on  which  the  file  was  first 
created. 

creation  time:  An  attribute  of  a  ProDOS  file;  it 
specifies  the  time  at  which  the  file  was  first 
created. 

C  string:  An  ASCII  character  string  terminated  by 
a  null  character  (ASCII  value  =  0). 

cursor:  A  symbol  displayed  on  the  screen 
marking  where  the  user's  nejtt  action  will  take 
effect  or  where  the  next  character  typed  from  the 
keyboard  will  appear. 

cut:  To  remove  something  by  selecting  it  and 
choosing  Cut  from  the  Edit  menu.  The  cut 
portion  is  placed  on  the  Clipboard. 

data  areai  A  document  as  viewed  in  a  window. 
The  data  area  is  the  entire  document,  only  a 
portion  of  which  (the  visible  region)  may  be 
seen  in  the  window  at  any  one  time. 

data  bank  registeri  A  register  in  the  65816 
processor  that  contains  the  high-order  byte  of 
the  24-bit  address  that  references  data  in 

memory. 

data  bus:  A  set  of  the  electrical  conductors  that 
carry  data  from  one  internal  part  of  the 
computer  to  another. 

data  structure:  A  specifically  formatted  item  of 
data  or  a  form  into  wliich  data  may  be  placed, 

DB  register:  Sec  data  bank  register. 
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debugger:  A  utility  used  for  sofiwarc  development 
that  allows  you  to  analyze  a  program  for  errors 
that  cause  it  to  malfunction.  For  example,  it  may 
allow  you  to  step  through  execution  of  the 
program  one  instruction  at  a  time, 

default  prefix:  The  pathname  prefix  attached  by 
ProDOS  l6  to  a  partial  pathname  when  no  prefix 
number  is  supplied  by  the  application.  The 
default  prefix  is  equivalent  lo  prefix  number  0/. 

definition  procedure:  A  routine  that  defines  the 
characteristics  of  some  desktop  feature  such  as  a 
window  or  control.  For  example,  TaskMaster 
needs  a  pointer  to  a  window-content  deflnUon 
pwcedure (yiCoutDetP roc}  in  order  to  draw  the 
contents  of  windows  that  it  manipulates. 

DdProa  See  definition  procedure. 

dereference:  To  substitute  a  pointer  for  a 
memory  handle,  or  a  value  for  a  pointer.  When 
you  dereference  a  memory  block's  handle,  you 
access  the  block  direcdy  (through  its  master 
pointer)  rather  than  indirectly  (through  its 
handle). 

descender:  Any  part  of  a  character  that  lies 
below  the  base  line  (such  as  the  tail  on  a  lower- 
case "p">  . 

descent:  In  a  font,  the  distance  between  the  base 
line  and  the  descent  Une. 

descent  line:  A  horizontal  line  that  coincides  with 
the  bottom  of  the  character  descender  that 
extends  farthest  below  the  base  line.  See  also 
ascent  Hue,  font  height. 

desk  accessory:  A  "mini-apprication"  that  is 
available  to  the  user  regardless  of  whether 
another  application  is  njnning.  The  Apple  IIGS 
supports  two  t\'pes  of  desk  accessories:  classic 
disk  accessories  and  new  desk  accessories. 

desk  accessory  events  An  event  that  occurs  when 
the  user  enters  the  special  keystroke 
(Control-Apple-Escape)  to  invoke  a  cl^sic  desk 
accessory. 


Desk  Manager;  Tlae  Apple  IIGS  tool  set  that 
executes  desk  accessories  and  enables 
applications  lo  support  them. 

desk  scrap:  A  piece  of  data,  maintained  by  the 
Scrap  Manager,  taken  from  one  application  and 
available  for  insertion  into  another. 

desktop:  The  visual  interface  between  the 
computer  and  the  user — the  menu  bar  and  the 
gray  (or  solid-colored)  area  on  the  screen.  In 
many  applications  the  user  can  have  a  number  of 
documents  on  the  desktop  at  the  same  time, 

desktop  intertacc:  See  desktop. 

destination;  See  destination  kicatlorL 

destination  location:  The  location  (memory 
buffer  or  portion  of  the  QuickDraw  II  coordinate 
plane)  to  which  data  such  as  text  or  graphics  is 
copied.  Compare  source  location.  See  also 
destination  rectangle. 

destination  rectangle;  The  rectangle  (on  the 
QuickDraw  11  coordinate  plane)  in  which  text  or 
graphics  are  drawn  when  transferred  from 
somewhere  else.  Compare  source  rectangle. 

development  environment;  A  program  or  set  of 
programs  that  allows  you  to  write  applications.  It 
typically  consists  of  a  text  editor,  an  assembler  or 
compiler,  a  linker,  and  support  programs  such  as 
a  debugger. 

device:  A  piece  of  hardware  used  in  conjunction 
with  a  computer  and  under  the  computer's 
control.  Also  called  a  peripheral  device  because 
such  equipment  is  often  physically  separate  from, 
but  attached  to,  the  computer. 

device  driver:  A  program  that  handles  the 
transfer  of  data  to  and  from  a  peripheral  device, 
such  as  a  printer  or  disk  drive, 

device-driver  event:  An  event  generated  by  a 
device  driver. 
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dials  An  indicator  on  ihc  screen  lhal  displays  A 
quanlalivc  selling  or  value.  Usually  found  in 
analog  form,  such  as  a  fuel  gauge  or 
thermometer.  A  scroll  bar  is  a  standard  type  of 
dial. 

dialog;  See  dialog  box, 

dialog  box:  A  box  on  the  screen  that  contains  a 
message  requesting  mofe  information  from  the 
user.  See  also  alert. 

Dialog  Manager:  The  Apple  IIGS  tool  set  that 
manipulates  dialog  boxeK  and  alerts,  which 
appear  on  the  screen  when  an  application  needs 
more  information  to  carry  out  a  command  or 
when  the  user  needs  to  be  noiified  of  an 
important  situation. 

dialog  record;  information  describing  a  dialog 
window  that  is  maintained  by  the  Dialog 
Manager. 

dialog  window;  The  window  in  whidi  a  dialog  box 
appears. 

digital  oscillator  chip  (DOC):  An  integrated 
circuit  in  the  Apple  IIGS  that  contains  32  digital 
oscillators,  each  of  which  can  generate  a  sound 
from  stored  digital  waveform  data. 

digital  RGB  video  monitor:  A  type  of  RGB  video 
display  in  which  the  intensities  of  the  red,  green, 
and  blue  signals  are  fixed  at  discrete  values. 

dim:  On  the  Apple  IIGS  desktop,  to  display  a 
control  or  menu  item  in  gray  rather  than  black, 
to  notify  the  user  that  the  item  is  Inactive. 

direct  pages  A  page  (256  bytes)  of  bank  $00  of 
Apple  IIGS  memory,  any  part  of  which  can  be 
addressed  wiLh  a  short  (one-byte)  address 
because  its  high-order  address  byte  is  always  SOO 
and  its  middle  address  byte  is  the  value  of  the 
65816  direct  register.  Co-resident  programs  or 
routines  can  have  their  own  direct  pages  at 
different  locations.  The  direct  page  corresponds 
to  the  6502  processor's  iero  page.  The  term 
direct  page  is  often  used  informally  to  refer  to 
any  part  of  the  direa-p age/stack  space. 


direct- page/stack  segment  A  program  segment 
that  is  used  to  initialize  the  size  and  contents  of 
an  application's  stack  and  direct  page.  i 

direct- page/stack  space:  A  single  block  of 
memory  that  contains  an  application's  stack  and 
direct  page. 

direct  register:  A  hardware  register  in  the  65S16 
processor  that  specifies  the  start  of  the  direct 
page. 

disable:  To  make  unresponsive  to  user  actions.  A 
dialog  box  control  that  is  disabled  does  nothing 
when  selected  or  manipulated  by  the  user.  In 
appearance,  however,  it  is  identical  to  an  enabled 
control,  Compare  inactive. 

disabled  menu:  A  menu  that  can  be  pulled  down, 
but  whose  items  are  dimmed  and  not  sclcciable. 

disassembler:  A  program  that  converts  machine- 
language  code  in  memory  into  assembly- 
language  instructions.  Opposite  of  assembler. 

disk  operating  system:  An  operating  system 
whose  principle  function  is  to  manage  disk-based 
file  access. 

disk  porb  The  connector  on  the  rear  panel  of  the 
Apple  IIGS  for  attaching  disk  drives. 

Disk  U:  A  type  of  disk  drive  made  and  sold  by 
Apple  Computer,  Inc.,  for  use  with  the  Apple  n,  II 
Plus,  and  lie  computers.  It  uses  5.25-inch  disks. 

display  mode:  A  specification  for  the  way  in 
which  a  video  display  functions,  including  such 
parameters  as  whether  displaying  text  or 
graphics,  available  colors,  and  number  of  pixels. 
The  Apple  IIGS  has  two  text  display  modes  (.40 
column  and  80  column),  two  standard  Apple  II 
graphics  display  modes  (Hi-Jles  and  Double 
Hi -Res),  and  two  new  Super  Hi -Res  graphics 
display  modes  (320  mode  and  6'10  mode). 

display  rectangle;  A  rectangle  that  determines 
where  an  item  is  displayed  within  a  dialog  box. 
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dispose:  To  permanenlly  deallocate  Ca  memory 
block).  The  Memory  Manager  disposes  of  a 
memory  block  by  removing  its  master  pointer. 
Any  handle  to  that  pointer  will  then  be  invalid. 
Compare  purge. 

dithering:  A  technique  for  alternating  the  values 
of  adjacent  pixels  to  create  the  optical  effect  of 
intermediate  values.  Dithering  can  give  the  effect 
of  shades  of  gray  on  a  black-and-white  display,  or 
more  colors  on  a  color  display, 

DOO  See  digital  oscillator  chip. 

document!  A  file  created  by  an  application. 

document  window:  A  window  that  displays  a 
document.  One  of  the  two  predefined  window 
formats.  Compare  alert  window. 

dormant;  Said  of  a  program  thai  is  not  being 
executed,  but  whose  essential  pares  are  a!!  in  the 
computer's  memory.  A  dormant  program  may 
be  quickly  restarted  because  it  need  not  be 
reloaded  from  disk. 

double  click:  To  position  the  pointer  where  you 
want  an  action  to  take  place,  and  then  press  and 
release  the  mouse  button  twice  in  quick 
succession  without  moving  the  mouse. 

draft  printing;  The  print  method  that  the 
LaserWriter  uses,  QuickDraw  II  calls  are  convened 
directly  into  command  codes  the  printer 
understands,  which  are  then  immediately  used  to 
drive  the  printer,  Compare  spool  printing, 

dragj  To  position  the  pointer  on  something, 
press  and  hold  the  mouse  button,  move  the 
mouse,  and  release  the  mouse  button.  When  you 
release  the  mou.se  button,  you  either  confirm  a 
menu  selection  or  move  an  object  to  a  new 
location. 

drag  areau  A  subregion  in  a  window  (usually  the 
title  bar)  in  which  the  mouse  pointer  must  be 
placed  before  the  user  can  drag  the  window, 

draw:  In  QuickDraw  II,  to  color  pixels  in  a  pixel 
image. 


drawing  environment;  The  complete  description 
of  how  and  where  drawing  may  take  place.  Every 
open  window  on  the  Apple  IIGS  screen  is 
associated  with  a  GrafPort  record,  which  specifies 
the  window's  drawing  environment.  Same  as  port, 
graphic  port 

drawing  mask:  An  S-bit  by  8-bil  pattern  that 
conu-ols  which  pixels  in  the  QuickDraw  pen  will 
be  modified  when  the  pen  draws. 

drawliig  mode:  One  of  eight  possible  interactions 
between  pixels  in  QuickDraw  ll's  pen  pattern  and 
pixels  already  on  the  screen  that  fall  under  the 
pen's  path.  In  COPY  mode,  for  example,  pixels 
already  on  the  screen  are  ignored.  In  XOR  mode, 
on  the  other  hand,  bits  in  pixels  on  the  screen 
are  XOR'd  with  bits  in  pixels  in  the  pen;  the 
resulting  pixels  are  drawn  on  the  screen. 

drawing  pen;  See  pen. 

D  register;  See  direct  register. 

driver;  See  device  driver. 

dynamic  segment;  A  load  segment  capable  of 
being  loaded  during  program  execution. 
Compare  static  segment 

edit  record:  A  complete  text  editing  environment 
in  the  Line  Edit  Tool  Set,  which  includes  the  text 
to  be  edited,  the  GrafPort  and  rectangle  in  which 
to  display  the  text,  the  arrangement  of  the  text 
within  the  rectangle,  and  other  editing  and 
display  information. 

e  flag:  One  of  three  flag  bits  in  the  65816 
processor  that  programs  use  to  control  the 
processor's  operating  modes.  The  setting  of  the  e 
flag  determines  whether  the  processor  is  in 
native  mode  (6502),  or  emulation  mode  (65816). 
See  also  m  flag  and  x  flag. 

emulate;  To  operate  in  a  way  identical  to  a 
different  system.  For  example,  the  65816 
microprocessor  in  the  Apple  IlGS  can  carry  out 
all  the  instructions  in  a  program  originally 
written  for  an  Apple  II  that  uses  a  6502 
microprocessor,  thus  emulating  the  6502. 
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emulation  mode:  The  S-bit  configuraiion  of  the 
65816  processor  in  which  it  functions  like  a  6502 
processor  in  all  respects  except  dock  speed 

enable:  To  make  responsive  to  user  manipulaLion. 
A  dialog  or  menu  that  is  enabled  can  be  selected 
by  the  user,  Enabling  does  not  affect  how  an  item 
is  displayed.  Compare  activate. 

end-of-me;  See  EOF, 

EOF:  The  logical  size  of  a  ProDOS  16  file;  it  is  the 
number  of  bytes  that  may  be  read  from  or 
written  lo  the  file. 

erase;  In  QuickDraw  II,  to  color  an  area  with  the 
bachgnMind  pattern. 

error:  Tlie  state  of  a  computer  after  it  has 
detected  a  fault  in  one  or  more  commands  sent 
to  it.  Also  called  error  condition. 

error  message:  A  message  issued  by  the  system  or 
application  program  when  it  has  encountered  an 
abnormal  situation  or  an  error  in  data. 

event:  A  notification  to  an  application  of  some 
occurrence  (such  as  an  interrupt  generated  by  a 
keypress)  to  which  the  application  may  want  to 
respond. 

event  code:  A  numeric  value  assigned  to  each 
event  by  the  Event  Manager.  Compare  task  code. 

event-driven:  A  kind  of  program  that  responds  to 
user  inputs  in  real  time  by  repeatedly  testing  for 
events.  An  event-driven  program  does  nothing 
until  it  detects  an  event  such  as  a  dick  of  the 
mouse  button. 

Event  Manager:  An  Apple  IIGS  tool  set  that 
detects  events  as  they  happen,  and  passes  the 
events  on  to  the  application  or  to  the 
appropriate  event  handler,  such  as  TaskMaster. 

event  mask:  A  parameter  passed  to  an  Event 
Manager  routine  to  specify  which  types  of  events 
the  routine  should  apply  to. 

event  queue:  A  list  of  pending  events  maintained 
by  the  Event  Manager. 
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event  record:  The  internal  representation  of  an 
event,  through  which  your  program  learns  all 
pertinent  information  about  that  event. 

execution  mode:  One  of  two  general  slates  of 
execution  of  the  65316  processor — native  mode 
and  6502  emulation  mode. 

extended  task  event  record;  A  data  structure 
based  on  the  event  record  that  contains 
information  used  and  returned  by  TaskMaster. 

FALSE:  Zero.  The  result  of  a  Boolean  operation. 
Opposite  of  TRUE, 

file:  Any  named,  ordered  collection  of 
information  stored  on  a  disk.  Application 
programs  and  operating  systems  on  disks  are 
examples  of  files;  so  also  are  text  or  graphics 
created  by  applications  and  saved  on  disks.  Text 
and  grapliics  files  are  also  called  documentS- 

flle  leveL  See  system  file  leveL 

file  mark:  See  Mark. 

filename;  The  string  of  characters  that  identifies 
particular  file  within  its  directory.  ProDOS 
filenames  may  be  up  to  15  characters  long. 
Compare  pathname. 

file  type:  An  attribute  of  a  ProDOS  file  that 
characterizes  its  contents  and  indicates  how  the 
file  may  be  used,  On  disk,  file  types  are  stored  as 
numbers;  in  a  directory  listing,  they  are  often 
displayed  as  three-character  or  single- word 
mnemonic  codes. 

fill  mode:  A  display  option  in  Super  Hi-Res  320 
mode,  In  fill  mode,  pixels  in  memory  with  the 
value  0  are  automatically  assigned  the  color  of 
the  previous  nonzero  pixel  on  the  scan  line;  the 
program  thus  need  assign  explicit  pixel  values 
only  to  change  pixel  colors. 


firmware:  Programs  stored  permanently  in  ROM; 
most  provide  an  interface  to  system  hardware. 
Such  programs  (for  example^  the  Monitor 
program)  are  built  into  the  computer  at  the 
factory.  They  can  be  executed  at  any  lime  but 
cannot  be  modified  or  erased.  Compare 
haithviare  and  software. 

fixed:  Not  movable  in  memory  once  allocated. 
Also  called  immovable.  Program  segments  that 
must  not  be  moved  are  placed  in  fixed  memory 
blocks.  Opposite  of  movable. 

fixed- address:  A  memory  block  that  must  be  at  a 
specified  address  when  allocated. 

fixed-bank:  A  block  of  memory  that  must  start  in 
a  specified  bank. 

flag;  A  variable  whose  value  (usually  1  or  0, 
standing  for  true  or  false)  indicates  whether  some 
condition  holds  or  whether  some  event  has 
occurred.  A  flag  is  used  to  control  the  program's 
actions  at  some  later  lime, 

folden  See  subdirectory, 

fonu  In  typography,  a  complete  sei  of  type  in  one 
size  and  style  of  character,  In  computer  usage,  a 
collection  of  letters,  numbers,  punctuation  marks, 
and  other  typographical  symbols  with  a 
consistent  appearance;  the  size  and  style  can  be 
changed  readily.  See  also  font  scaling. 

font  family:  All  fonts  that  share  the  same  name 
but  may  vary  in  size  or  style.  For  example,  all 
fonts  named  Helvetica  are  in  the  same  family, 
even  though  that  family  contains  Helvetica, 
Helvetica  Narrow  and  Helvetica  Bold. 

font  height;  The  vertical  distance  from  a  font's 
ascent  line  to  its  descent  line. 

font  ID:  A  number  that  specifies  a  font  by  family, 
style,  and  size. 

font  scaling:  A  process  by  which  the  Font 
Manager  creates  a  font  at  one  size  by  enlarging 
or  reducing  characters  in  an  existing  font  of 
another  size. 


font  strike:  A  1  bit/pixel  pixelmap  consisting  of 
the  character  images  of  every  defined  character 
in  the  font,  placed  sequentJaHy  in  order  of 
increasing  ASCII  code. 

foreground  color:  The  color  of  the  foreground 
pixels  in  text;  by  default  it  is  white. 

foreground  pixels;  In  a  character  Image,  the 

pixels  corresponding  to  the  character  itself. 

frame  region;  ITie  part  of  a  window  that 
surrounds  the  window's  content  region  and 
contains  standard  window  controls, 

fvU  piictmame:  The  complete  name  by  which  a 
file  is  specified,  starting  with  the  volume 
directory  name.  A  full  pathname  always  begins 
with  a  slash  (/),  because  a  volume  directory 
name  always  begins  with  a  slash.  See  also 
pathname. 

FuncUon  Pointer  Table  CFFO:  A  table, 
maintained  by  the  Tool  Locator,  that  points  to  all 
routines  in  a  given  tool  set. 

general  logic  unit  See  GLU. 

GetNextEvent  The  Event  Manager  call  that  an 
application  can  make  on  each  cycle  through  its 
main  event  loop.  Compare  TaskMaster. 

global  coordinates:  The  coordinate  system 
assigned  to  a  pixel  image  (such  as  screen 
memory)  to  which  QuickDraw  II  draws.  In  glob:il 
coordinates,  the  origin  (upper-left  corner)  of  the 
pixel  image's  boundary  rectangle  ha,'!  the  value 
(0,0).  Compare  local  coordinates. 

global  symbol;  A  label  in  a  segment  that  may  be 
referenced  by  other  segments.  Compare;  with 
local  symbol,  private  symboL 

GLU:  Abbreviation  of  general  logic  unit,  a  class  of 
custom  integrated  circuits  used  as  interfaces 
between  different  parts  of  the  computer. 

go-away  area;  A  subregion  in  a  window  frame, 
corresponding  to  the  close  box.  Clicking  inside 
this  region  of  the  active  window  makes  the 
window  close  or  disappear. 
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GrafPort:  A  data  slructure  (record)  Lhai  specifies 
a  complete  drawing  environment,  including  such 
elements  as  a  pixel  image,  boundaries  within 
which  to  draw,  a  character  font,  patterns  for 
drawing  and  erasing,  and  other  pen 
characterislics- 

graphlG  Interface;  An  interface  between  computer 
and  user  in  which  all  screen  drawing  or  other 
output,  including  texi,  is  done  by  graphic 
routines.  Desktop  programs  use  a  graphic 
interface.  Compare  text-based  interface. 

graphic  port!  A  specification  for  how  and  where 
QuickDraw  II  draws.  A  graphic  port  is  defined  by 
its  GraitPort  record;  an  application  may  have 
more  that  one  graphic  port  open  at  one  time, 
each  defined  by  its  own  GrafPort.  Same  as 
drawing  environment 

grow  area:  A  window-frame  subregion  in  which 
dragging  changes  the  size  of  the  window. 

handle:  See  memory  handJe. 

hardware:  In  computer  terminology,  the 
machinery  that  makes  up  a  computer  system. 
Compare  firmware,  software. 

Heartbeat  Interrupt  Task  queue:  A  list  of  tasks, 
such  as  cursor-movement  updating  or  checking 
stack  size,  to  be  performed  during  vertical 
blanking.  Heartbeat  tasks  are  manipulated  by  the 
Miscellaneous  Tool  Set. 

Heartbeat  routines!  Routines  that  execute  at  some 
multiple  of  the  heartbeat  interrupt  signal,  which 
occurs  during  the  vertical  blanking  interval 
(every  '/io  of  a  second). 

hex:  See  bcTi^deciniid. 

hexadecimal;  The  representation  of  numbers  in 
the  b3se-l6  system,  using  the  ten  digits  0  through 
9  and  the  six  letters  A  through  F.  Each 
hexadecimal  digit  corresponds  to  a  sequence  of 
four  binary  digits  (bits).  Hexadecimal  numbers 
are  usually  preceded  by  a  dollar  sign  ($). 
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hide:  To  make  invisible  (but  not  necessarily  to 
discard)  an  object  on  the  screen  such  as  a 
window. 

highlight:  To  make  something  visually  distinct. 
For  example,  when  a  button  on  a  dialog  box  is 
selected,  it  appears  as  light  letters  on  a  dark 
background,  rather  than  dark-on-light.  An  active 
window  or  control  is  highlighted  differently  than 
an  inactive  one. 

HodgePodge:  A  sample  Apple  ITGS  desktop 
application;  the  program  described  in  this  book. 

horizontal  blanking:  The  interval  between  llie 
drawing  of  each  scan  line  on  a  video  display. 

Human  Interface  Guidelines:  Apple  Computer's 
set  of  conventions  and  suggestions  for  writing 
desktop  programs.  Programs  that  follow  the 
Human  Interface  Guidelines  present  a  consistent 
and  friendly  interface  to  users. 

IC:  See  integrated  drculL 

icon:  An  image  that  graphically  represents  an 
object,  a  concept,  or  a  message. 

i  flag:  A  bit  in  Ihc  65Sl6  microprocessor's 
Processor  Status  register  that,  if  set  to  1,  disables 
interrupts. 

image:  A  representation  of  the  contents  of 
memory,  A  code  image  consists  of  machine- 
language  instructions  or  data  tliat  may  be  loaded 
unchanged  into  memory.  See  also  pixel  image. 

inactive:  Controls  that  have  no  meaning  or  effect 
in  the  current  context,  such  as  an  Open  button 
when  no  document  has  been  .selected  to  be 
opened.  These  inactive  controls  are  not  affected 
by  the  user's  mouse  actions  and  are  dimmed  on 
the  screen.  Compare  disable. 

index  register;  A  register  in  a  computer  processor 
that  holds  an  index  for  use  in  indexed 
addressing.  The  6S02  and  65816  microprocessor.') 
used  in  the  Apple  II  family  of  computers  have 
two  index  registers,  called  the  X  register  and  the 
Y  register,  | 


inforniation  bar:  An  optional  component  of  a 
window.  If  present,  the  informaiion  bar  appears 
just  below  the  title  bar.  U  may  contain  any 
information  the  application  that  created  the 
window  wishes. 

InitiaUiatlon  fllei  A  program  (in  the 
SYSTEM,  SETUP  subdirectory  of  the  boot  disk) 
that  is  loaded  and  executed  at  system  startup, 
independently  of  any  application. 

initialization  segnaentj  A  segment  in  an  initial 
load  file  that  is  loaded  and  executed 
independently  of  the  rest  of  the  program,  li  is 
commonly  executed  first,  to  perform  any 
initialization  that  the  program  may  require. 

input^outpub  See  I/O. 

Insertion  point:  The  place  in  a  document  where 
something  will  be  added;  it  is  selected  by  clicking 
and  is  normally  represented  by  a  blinking 
vertical  bar. 

instrumenti  A  data  stmcture,  used  by  the  Note 
Sequencer  and  Synthesizer,  that  specifies  such 
parameters  as  the  amplitude  envelope,  pitchbend 
and  vibrato  characteristics,  and  the  specific 
waveforms  thai  characterize  the  sound  to  be 
played. 

integer;  A  whole  number  in  fixed-point  form. 

Integer  Math  Tool  Set;  The  Apple  IIGS  tool  set 
that  performs  simple  malhemaiical  functions  on 
integers  and  other  fixed-point  numbers  and 
converts  numbers  to  their  ASCII  string 
equivalents. 

integrated  circuit  An  electronic 
circuit — including  components  and 
interconnections — entirely  contained  in  a  single 
piece  of  semiconducting  material,  usually  silicon, 
Often  referred  to  as  a  chip- 

interface:  CD  The  general  form  of  interaction 
between  a  user  and  a  computer.  (2)  In 
programming,  the  compi!e-time  and  runtime 
linkage  between  your  program  and  toolbox 
routines. 


interface  library:  A  set  oi  vanaoie  aennmuiis  diiu 
data -structure  definitions  that  link  a  program 
(such  as  a  C  application)  with  software  written  in 
another  language  (such  as  the  Apple  IIGS 
Toolbox), 

interrupt:  A  temporary  suspension  in  the 
execution  of  a  main  program  that  allows  the 
computer  to  perform  some  other  task,  typically 
in  response  to  a  signal  from  a  peripheral  device 
or  other  source  external  lo  the  computer. 

interrupt  environment:  The  machine  state, 
including  register  length  and  contents,  within 
which  the  interrupt  handler  executes. 

invert;  To  highlight  by  changing  white  pixels  to 
black  and  vice  versa. 

I/O;  Input/Output.  A  general  term  that 
encompasses  input/output  activity,  the  devices 
that  accomplish  it,  and  the  dau  involved, 

I/O  space:  The  portion  of  the  memory  map  in  a 
standard  Apple  II  (and  in  banks  $00,  $01,  $E0, 
and  SEl  of  an  Apple  IIGS)  with  addresses 
between  SCOOO  and  SCFFF.  Programs  perform 
I/O  by  writing  to  or  reading  from  locations  in 
this  I/O  space. 

item:  A  component  of  a  dialog  box,  such  as  a 
button,  text  field,  or  icon, 

item  ID:  A  unique  number  that  defines  an  item  in 
a  dialog  box  and  allows  further  reference  to  it. 

item  line:  The  line  of  text  that  defines  a  menu 

item's  name  and  appearance, 

item  list;  A  list  of  information  about  all  the  items 
in  a  dialog  or  alert  box. 

item  type:  Identifies  the  type  of  dialog  item, 
usually  represented  by  a  predefined  constant 
(such  as  edit  Line)  or  a  series  of  constants 
(such  as  editLine+iteniDisable). 

Job  dialog  box;  A  dialog  box  presented  when  the 
user  selects  Print  from  the  File  menu. 
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Joystick;  A  peripheral  device  with  a  lever, 
typically  used  to  move  creatures  and  objects  in 
game  programs;  a  joystick  can  also  be  used  in 
applications  such     computer-aided  design  and 
graphics  programs. 

JSD  Jump  to  Subroutine  (Long),  a  65816  assembly- 
language  instruction  that  requires  a  long  C3-bySe) 
address.  JSL  can  be  used  to  transfer  execution  to 
code  in  another  memory  bank. 

JSR:  Jump  to  SubfOuUne,  a  6502  and  65816 
assembly- language  instruction  that  requires  a  2- 
byte  address. 

Jump  Table:  A  table  constmcted  in  memory  by 
the  System  Loader,  Tlie  Jump  Table  contains  all 
references  to  dynamic  segments  that  may  be 
called  during  execution  of  the  program, 

See  kilobyte. 

keyboard  equlvalenu  The  combination  of  the 
Apple  key  and  another  key,  used  to  invoke  a 
menu  item  from  the  keyboard, 

key-down:  An  event  type  caused  by  Uie  user's 
pressing  any  character  key  on  the  keyboard  or 
keypad.  The  character  keys  indude  all  keys  except 
Shift,  Caps  Lock,  Control,  Option,  and  Apple, 
which  are  called  modifier  keys.  Modifier  keys  are 
treated  differently  and  generate  no  keyboard 
events  of  their  own. 

kilobyte  (K):  A  unit  of  measurement  consisting  of 
1024  (2l0>  bytes.  In  this  usage,  kilo  (from  the 
Greek,  meaning  a  thousand)  stands  for  1024. 
Thus,  64K  memory  equals  65,536  bytes.  See  also 
megabyte. 

kind:  See  segment  kind. 


language  card:  Memory  with  addresses  between 
SDOOO  and  SFFFF  in  any  Apple  Il-family 
computer.  It  includes  two  RAM  banks  in  the 
SDjoDf  space,  called  bank-switched  memory.  The 
language  card  was  originally  a  peripheral  card 
for  the  4SK  Apple  II  or  Apple  11  Plus  that 
expanded  the  computer's  memory  capacity  to 
64K  and  provided  space  for  an  additional  diale 
of  BASIC. 

leading;  (Pronounced  LED-ing.)  The  space 
between  lines  of  text.  It  is  the  number  of  pixels 
vertically  between  the  descent  line  of  one 
character  and  the  ascent  line  of  the  character 
immediately  beneath  it. 

lecigtb  byte;  The  first  byte  of  a  Pascal  string.  It 

specifies  the  length  of  the  string,  in  bytes, 

library  (or  library  file):  An  object  file  conuining 
program  segments,  each  of  which  can  be  used  in 
any  number  of  programs.  The  linker  can  search 
through  the  library  file  for  segments  that  have 
been  referenced  in  the  program  source  file, 

library  dictionary  segment:  The  first  segment  of  a 
library  file;  it  contains  a  list  of  all  the  symbols  in 
the  file  together  with  their  locations  in  the  file, 
The  linker  uses  the  library*  dictionary  segment  to 
find  the  segments  it  needs. 

line:  In  QuickDraw  II,  the  straight-line  trajectory 
between  two  points  on  the  coordinate  plane.  The 
line  is  specified  by  its  starting  and  ending  points, 

LineEdit  Tool  Set;  The  Apple  IIGS  tool  set  that 
provides  simple  text-editing  functions.  It  is  used 
mostly  in  dialog  boxes. 

line  beighti  The  total  amount  of  vertical  space 
from  line  to  line  in  a  text  document.  Line  height 
is  the  sum  of  ascent,  descent,  and  leading, 

LlnkEd:  A  command  language  that  can  be  used  to 
control  the  APW  Linker. 

linker:  A  program  that  combines  files  generated 
by  compilers  and  assemblers,  resolves  all 
symbolic  references,  and  generates  a  file  that  can 
be  loaded  into  memory  and  executed. 
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Lisa:  A  model  of  Apple  computer;  the  Tirst 
computer  that  offered  windows  and  Lhe  use  of  a 
mouse  to  choose  commands.  The  Lisa  is  now 
knowri  as  the  Macintosh  XL, 

list:  See  list  controL 

list  control:  A  custom  control  created  by  the  List 
Manager.  It  is  a  scrollable,  vertical  arrangement 
of  similar  items  on  the  screen;  tiie  items  are 
selectable  by  the  user. 

list  Manager:  The  Apple  ITGS  tool  set  that  allows 
an  applicaLion  to  present  the  user  with  a  list  from 
which  to  choose.  For  example,  the  Font  Manager 
uses  the  Ost  Manager  to  arrange  lists  of  fonts. 

load:  To  transfer  information  from  a  peripheral 
storage  medium  (such  as  a  disk)  into  main 
memory  for  use — for  example,  to  transfer  a 
program  into  memory  for  execution. 

load  file:  The  output  of  the  linker.  Load  files 
contain  memory  images  that  the  system  loader 
can  load  into  memory,  together  with  relocation 
dictionaries  that  the  loader  uses  to  relocate 
references. 

load  segment:  A  segment  in  a  load  file.  Any 
number  of  object  segments  can  go  into  the  same 
load  segment. 

local  coordinates:  A  coordinate  system  unique  to 
each  GrafPort  and  independent  of  the  global 
coordinates  of  the  pixel  image  that  the  port  is 
associated  with.  For  example,  local  coordinates 
do  no:  change  as  a  window  is  dragged  across  the 
screen;  global  coordinates  do  not  change  as  a 
window's  contents  are  scrolled. 

local  symboL  A  label  defined  only  within  an 
individual  segment.  Other  segments  cannot 
reference  the  label.  Compare  with  global  symboL 

Loclnfo:  Acronym  for  location  information.  The 
data  structure  (record)  that  ties  the  coordinate 
plane  to  an  individual  pixel  image  in  memory. 


Jock:  To  prevent  a  memory  block  from  being 
moved  or  purged.  A  block  may  be  locked  or 
unlocked  by  a  call  to  the  Memory  Manager. 

long  (or  long  word)i  On  the  Apple  liGS,  a  32-bit 
(4- byte)  data  type. 

Macintosh:  A  family  of  Apple  computers;  for 
example,  the  Macintosh  512K  and  the  Macintosh 
Plus.  Macintosh  computers  have  high-resolution 
screens  and  use  mouse  devices  for  choosing 
commands  and  for  drawing  pictures. 

macro:  A  single  keystroke  or  command  that  a 
program  replaces  with  several  keystrokes  or 
commands.  For  example,  the  APW  Editor  allows 
you  to  define  maaos  that  execute  several  editor 
keysuokc  commands;  the  APW  Assembler  allows 
you  to  define  macros  that  execute  instructions 
and  directives.  Macros  are  almost  like  higher- 
level  language  instructions,  making  assembly- 
language  programs  easier  to  write  and  complex 
keystrokes  easier  to  execute. 

macro  Ubf  aryi  A  file  of  related  maaos. 

main  event  loop:  The  central  routirie  of  an  event- 
driven  program.  During  execution,  the  program 
continually  cycles  through  the  main  event  loop, 
branching  off  to  handle  events  as  they  occur  and 
then  returning  to  the  event  loop. 

mainiD:  A  subfield  of  the  User  ID.  Each  running 
program  is  assigned  a  unique  mainlD. 

manager:  See  tool  set. 

Mark:  The  current  position  in  an  open  file.  It  is 
the  point  in  the  file  at  which  the  next  read  or 
write  operation  will  occur. 

mask:  (n)  A  parameter,  typically  one  or  more 
bytes  long,  whose  individual  bits  arc  used  to 
permit  or  block  particular  features.  See,  for 
example,  event  mask,  (v)  To  apply  a  mask. 

master  color  value:  A  2-byie  number  that 
specifies  the  relative  intensities  of  the  red,  green, 
and  blue  signals  output  by  the  Apple  IKS  video 
hardware. 
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Lisa:  A  model  of  Apple  computer;  the  Tirst 
computer  that  offered  windows  and  Lhe  use  of  a 
mouse  to  choose  commands.  The  Lisa  is  now 
knowri  as  the  Macintosh  XL, 

list:  See  list  controL 

list  control:  A  custom  control  created  by  the  List 
Manager.  It  is  a  scrollable,  vertical  arrangement 
of  similar  items  on  the  screen;  tiie  items  are 
selectable  by  the  user. 

list  Manager:  The  Apple  ITGS  tool  set  that  allows 
an  applicaLion  to  present  the  user  with  a  list  from 
which  to  choose.  For  example,  the  Font  Manager 
uses  the  Ost  Manager  to  arrange  lists  of  fonts. 

load:  To  transfer  information  from  a  peripheral 
storage  medium  (such  as  a  disk)  into  main 
memory  for  use — for  example,  to  transfer  a 
program  into  memory  for  execution. 

load  file:  The  output  of  the  linker.  Load  files 
contain  memory  images  that  the  system  loader 
can  load  into  memory,  together  with  relocation 
dictionaries  that  the  loader  uses  to  relocate 
references. 

load  segment:  A  segment  in  a  load  file.  Any 
number  of  object  segments  can  go  into  the  same 
load  segment. 

local  coordinates:  A  coordinate  system  unique  to 
each  GrafPort  and  independent  of  the  global 
coordinates  of  the  pixel  image  that  the  port  is 
associated  with.  For  example,  local  coordinates 
do  no:  change  as  a  window  is  dragged  across  the 
screen;  global  coordinates  do  not  change  as  a 
window's  contents  are  scrolled. 

local  symboL  A  label  defined  only  within  an 
individual  segment.  Other  segments  cannot 
reference  the  label.  Compare  with  global  symboL 

Loclnfo:  Acronym  for  location  information.  The 
data  structure  (record)  that  ties  the  coordinate 
plane  to  an  individual  pixel  image  in  memory. 


Jock:  To  prevent  a  memory  block  from  being 
moved  or  purged.  A  block  may  be  locked  or 
unlocked  by  a  call  to  the  Memory  Manager. 

long  (or  long  word)i  On  the  Apple  liGS,  a  32-bit 
(4- byte)  data  type. 

Macintosh:  A  family  of  Apple  computers;  for 
example,  the  Macintosh  512K  and  the  Macintosh 
Plus.  Macintosh  computers  have  high-resolution 
screens  and  use  mouse  devices  for  choosing 
commands  and  for  drawing  pictures. 

macro:  A  single  keystroke  or  command  that  a 
program  replaces  with  several  keystrokes  or 
commands.  For  example,  the  APW  Editor  allows 
you  to  define  maaos  that  execute  several  editor 
keysuokc  commands;  the  APW  Assembler  allows 
you  to  define  macros  that  execute  instructions 
and  directives.  Macros  are  almost  like  higher- 
level  language  instructions,  making  assembly- 
language  programs  easier  to  write  and  complex 
keystrokes  easier  to  execute. 

macro  Ubf  aryi  A  file  of  related  maaos. 

main  event  loop:  The  central  routirie  of  an  event- 
driven  program.  During  execution,  the  program 
continually  cycles  through  the  main  event  loop, 
branching  off  to  handle  events  as  they  occur  and 
then  returning  to  the  event  loop. 

mainiD:  A  subfield  of  the  User  ID.  Each  running 
program  is  assigned  a  unique  mainlD. 

manager:  See  tool  set. 

Mark:  The  current  position  in  an  open  file.  It  is 
the  point  in  the  file  at  which  the  next  read  or 
write  operation  will  occur. 

mask:  (n)  A  parameter,  typically  one  or  more 
bytes  long,  whose  individual  bits  arc  used  to 
permit  or  block  particular  features.  See,  for 
example,  event  mask,  (v)  To  apply  a  mask. 

master  color  value:  A  2-byie  number  that 
specifies  the  relative  intensities  of  the  red,  green, 
and  blue  signals  output  by  the  Apple  IKS  video 
hardware. 
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master  User  ID:  The  value  of  a  User  ID, 
disregarding  the  contents  of  the  auxID  field.  If  an 
application  allocates  various  memory  blocks  and 
assigns  them  unique  ID's  consisting  of  different 
auxID  values  added  to  its  own  User  ID,  then  all 
will  share  the  same  Master  User  ID  and  all  can  be 
purged  or  disposed  with  a  single  call, 

Mb:  See  megabyte. 

megabyte  CMb)j  A  unit  of  computer  memory  or 
disk  drive  capacity  that  equals  1,048,576  bytes. 

megahertz  (MHi>!  A  unit  of  measurement  of 
frequency,  equal  to  1,000,000  *(?rfz  (cycles  per 
second);  abbreviated  MHz. 

memory  block;  See  block  (2). 

memory  expansion  card:  A  memory  card  that 
increases  Apple  IIGS  internal  memory  capacity 
beyond  256K,  up  to  8  megabytes 

memory  fragmentation:  A  condition  in  which 
free  (unallocated)  portions  of  memory  are 
scattered  because  of  repeated  allocation  and 
deallocation  of  blocks  by  the  Memory  Manager 

memory  handle:  A  number  that  i  den  Li  Res  a 
memory  block.  A  handle  is  a  pointer  to  a 
pointer— it  is  the  address  of  a  master  pointer, 
which  in  turn  contains  the  address  of  the  block. 

memory  Image  See  Image. 

Memory  Manager!  The  Apple  IIGS  tool  set  lhat 
manages  memory  use.  The  Memory  Manager 
keeps  track  of  how  much  memory  is  available, 
and  allocates  memory  blocks  to  hold  program 
segments  or  data. 

Memory  Segment  Table:  A  linked  list  in  memory, 
created  by  the  loader,  that  allows  the  loader  lo 
keep  track  of  the  segments  that  have  been  loaded 
into  memory. 

menu:  A  list  of  choices  presented  by  a  program, 
from  which  the  user  can  select  an  action.  See  also 
puJl-down  menu. 


menu  bar;  Hie  horizontal  strip  at  the  top  of  the 
screen  that  contains  menu  titles  for  the  pull-down 
menus, 

menu  ID:  A  number  in  the  menu  record  that 
identifies  an  individual  menu, 

menu  Unes  A  line  of  text  plus  code  characters 
that  defines  the  appearance  of  a  particular  menu 
title. 

Menu  Manager:  The  Apple  IIGS  tool  set  that 
maintains  the  puII-down  menus  and  the  items  in 
the  menus. 

m  flag:  One  of  3  flags  in  the  65816 
microprocessor's  Processor  Status  register  that 
controls  execution  mode,  When  the  m  llag  is  set 
to  1,  the  accumulator  is  8  bits  wide;  otherwise,  it  is 
16  bits  wide. 

MHz:  See  megahertz. 

microprocessor:  A  central  processing  unit  that  is 
contained  in  a  single  integrated  circuit.  The 
Apple  lies  uses  a  65816  microprocessor. 

minipalette:  In  Super  Hi-Res  640  mode,  a  quarter 
of  the  color  table.  Each  pixel  in  640  mode  can 
have  one  of  four  colors  specified  in  a 
minipalette. 

Miscellaneous  Tool  Set:  The  Apple  IIGS  cool  set 
that  includes  mostly  system-level  routines  that 
must  be  available  for  other  tool  sets. 

missing  symbol  In  a  font,  the  symbol  substituted 
for  any  ASCII  value  for  which  the  font  does  not 
have  a  defined  symbol.  In  the  Apple  IIGS  system 
font,  the  missing  symbol  is  a  box  containing  a 
question  mark. 

modal  dialog  box;  A  dialog  box  that  puts  the 
machine  in  a  state  such  that  the  user  cannot 
execute  functions  outside  of  the  dialog  box,  until 
the  dialog  box  is  closed. 

mode:  A  state  of  a  computer  or  system  that 
determines  its  behavior.  A  manner  of  operating. 
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modeless  dialog  box:  A  dialog  box  chat  lels  the 
user  take  other  action  besides  responding  to  the 
dialog  box.  Compare  modal  dialog  box. 

naodificatlon  date;  An  attribute  of  a  ProDOS  Tile, 
it  specifies  the  date  on  which  the  content  of  the 
file  was  last  changed. 

modification  time:  An  attribute  of  a  ProDOS  file; 
it  specifies  the  time  at  which  the  content  of  the 
file  was  last  changed. 

Monitor  program:  A  firmware  program  built  into 
the  ROM  of  Apple  11  computers,  used  for  directly 
inspecting  or  changing  the  contents  of  main 
memory  and  for  operating  the  computer  at  the 
machine-language  level. 

monospaced!  Said  of  a  font  whose  character 
widths  are  all  idenUcal.  Compare  proporUonaUy 
spaced. 

MOS:  Abbreviation  for  metai-oxide 
semiconductor,  a  method  of  fabricating 
integrated-circuits  on  silicon  by  using  layers  of 
silicon  dioxide  in  the  make-up  of  the  devices. 
Compare  CMOS. 

mouse;  A  small  device  that  the  user  moves 
around  on  a  flat  surface  next  to  the  computer. 
The  mouse  controls  a  pointer  on  the  screen 
whose  movements  correspond  to  those  of  the 
mouse.  The  pointer  selects  operations,  moves 
data,  and  draws  graphic  objects. 

mouse  button:  A  button  on  a  mouse  device  with 
which  the  user  selects  objects  on  the  screen. 

mouse-down;  An  action  or  an  event,  signifying 
that  the  user  has  pressed  the  mouse  button. 

roouse-TJp:  An  action  or  an  event,  signifying  that 
the  user  has  released  the  mouse  button. 

movable;  Able  to  be  moved  to  different  memory 
locations  during  program  execution  (a  memory 
block  attribute), 

native  mode:  The  1 6-bit  operating  configuration 
of  the  65816  microprocessor. 


NTJA:  See  new  desk  acc^sory. 

new  desk  accessory  (NDA):  A  desk  accessory 
designed  to  execute  in  a  desktop,  event-driven 
environment.  Compare  classic  desk  accessory, 

tiewUne  read  mode:  A  file-reading  mode  in  which 
each  character  read  from  the  file  is  compared  to 
a  specified  character  (called  ihe  newUns 
characler);  if  there  is  a  match,  the  read  is 
[crminated.  Newline  mode  is  typically  used  to 
read  individual  lines  of  text,  with  the  newline 
characler  defined  as  a  carnage  return, 

NewWindow  parameter  Ust  A  template 
describing  the  features  of  a  window  that  is  to  be 
created.  A  pointer  to  a  NewWindow  parameter 
list  is  a  required  input  to  the  NewWindow  call. 

NIL:  Pointing  to  a  value  of  0.  A  memory  handle  is 
NIL  if  the  address  it  points  to  is  filled  with  zeros. 
Handles  to  purged  memory  blocks  are  NIL 
Compare  null- 
Note  Sequencer:  The  Apple  II GS  tool  set  that 
makes  it  possible  to  play  music  asyndironously 
in  programs. 

Note  Synthralzer:  An  Apple  HQS  tool  set  that 
facilitates  aeation  and  manipulation  of  musical 
notes, 

null:  Zero.  A  pointer  i^  null  if  its  value  is  all  zeros. 
Compare  Nil- 
null  event  An  event  reported  when  there  are  no 
other  events  to  report. 

null  prefix:  A  prefix  of  zero  lengdi  (and  therefore 
nonexistent). 

object  file:  The  output  from  an  assembler  or 
compiler,  and  the  input  to  a  linker.  It  contains 
ma  chine -language  instmctions  as  well  as  other 
information.  Also  called  object  program  or 
object  code.  In  APW  an  object  file  cannot  be 
loaded  into  memory.  Compare  source  file,  load 
file. 
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object  module  format  (OMF):  The  file  format 
used  in  Apple  lIGS  object  files,  library  files,  and 
load  files. 

object  segment;  A  segment  in  an  objea  file. 

offset:  The  number  of  character  positions  or 
memory  locations  away  from  a  point  of 
reference. 

OKi  One  of  two  predefined  item  ID  numbers  for 
dialog  box  buttons  (OK  =  1).  Compare  Cancel. 

OMF:  See  object  module  format. 

operating  environment:  The  overall  hardware 
and  software  setting  within  which  a  program  runs. 
Also  called  execution  environment. 

operating  system;  A  general-purpose  program 
that  organises  the  actions  of  the  various  parLs  of 
the  computer  and  its  peripheral  devices,  See  also 
disk  oparatlng  system. 

origin;  (1)  The  first  memory  address  of  a 
program  or  of  a  portion  of  one.  The  first 
instruction  to  be  executed.  (2)  The  location  (0,0) 
on  the  QuickDraw  II  coordinate  plane,  in  either 
global  coordinates  or  local  coordinates.  (3)  The 
upper-left  corner  of  any  rectangle  (such  as  a 
boundary  rectangle  or  port  rectangle)  in 
QuickDraw  II,  (4)  See  character  origin. 

oscillator:  A  device  that  generates  a  vibration.  In 
the  Apple  IlGS  Digital  Oscillator  Chip,  an 
oscillator  is  an  address  generator  that  paints  to 
the  next  data  byte  in  memory  that  represents 
part  of  a  particular  sound  wave. 

oval:  A  circle  or  ellipse,  one  of  the  fundamcniai 
dasses  of  objects  drawn  by  QuickDraw  II. 

overlay:  One  of  a  set  of  program  segments  meant 
to  alternately  occupy  the  same  memory  space. 
Use  of  overlays  is  one  way  to  minimize  the 
amount  of  memory  a  program  needs. 

pack;  To  compress  data  into  a  smaller  space  to 
conserve  storage  space. 


page:  (1)  A  portion  of  memory  25 &  bytes  long 
and  beginning  at  an  address  that  is  an  even 
multiple  of  256-  Memory  blocks  whose  starting 
addresses  are  an  even  multiple  of  256  are  said  to 
be  page-aligned^  (2)  (usually  capitalized)  An  area 
of  main  memory  containing  text  or  graphic 
information  being  displayed  on  the  screen. 

page-aligned;  Starting  at  a  memory  address  that 
is  an  even  multiple  of  256  (a  memory  block 
attribute).  See  page  (1). 

palette;  The  full  set  of  colors  available  for  an 
individual  screen  pixel. 

parameter:  A  value  passed  to  or  from  a  function 
or  other  routine. 

parameter  RAM:  RAM  on  the  Apple  IlGS  dock 
chip,  A  battery  preserves  the  dock  settings  and 
the  RAM  contents  when  the  power  is  off  Control 
Panel  settings  are  kept  in  battery  RAM, 

partial  pathname;  A  pathname  that  includes  the 
filename  of  the  desired  file  but  excludes  the 
volume  directory  name  (and  possibly  one  or 
more  of  the  subdirectories  in  the  path).  It  is  the 
part  of  a  pathname  following  a  prefix— a  prefix 
and  a  partial  pathname  together  constitute  a  full 
pathname.  A  partial  pathname  does  not  begin 
with  a  slash  because  it  has  no  volume  directory 
name. 

Pascal;  A  high-level  programming  language. 
Named  for  the  philosopher  and  mathematician 
Blaise  Pascal, 

Pascal  string;  An  ASCII  character  string  preceded 
by  a  single  byte  whose  numerical  value  is  the 
number  of  characters  in  the  string.  Compare  C 
string. 

paste:  To  place  the  desk  scrap  (contents  of  the 
Clipboard — w/haiever  was  last  cut  or  copied)  at 
the  insertion  point. 
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patch:  To  replace  one  or  more  byies  in  memory 
or  in  a  file  with  other  values.  The  address  lo 
which  the  program  must  jump  to  execute  a 
subroutine  is  patched  into  memory  at  load  lime, 
when  the  System  Loader  performs  relocation  on 
a  file. 

pathname:  A  name  that  specifies  a  file.  Il  is  a 
sequence  of  one  or  more  filenames  separated  by 
slashes,  tracing  the  path  through  subdirectories 
that  a  program  must  follow  to  locate  the  file.  See 
Ml  pathname,  partial  pathname;,  prefix. 

pathname  prefix:  See  prefix. 

Pathname  Table:  A  table  constructed  in  memory 
by  the  System  Loader.  The  Pathname  Table 
contains  cross-references  between  load  files 
referenced  by  number  (in  the  Jump  Table)  and 
by  pathname  (in  the  file  directory), 

patterm  CI)  An  8-by-8  pixel  image,  used  to  define 
a  repeating  design  (such  as  stripes)  or  color.  (2) 
A  series  of  commands  to  the  Note  Synthesizer. 

PB  regjsten  See  program  bank  register, 

PC  register:  A  register  within  the  65816 
microprocessor  that  keeps  track  of  the  memory 
address  of  the  next  instruction  to  be  executed.  PC 
stands  for  program  counter. 

pem  The  conceptual  tool  with  which  QuickDraw  11 
draws  shapes  and  characters.  Each  GrafPort  has 
its  own  pen, 

pen  location:  The  position  (on  the  coordinate 
plane)  at  which  the  next  character  or  line  will  be 
drawn. 

pen  pattern:  See  pattern  (1). 

peripheral  card:  A  hardware  device  placed  inside 
a  computer,  and  connected  to  one  of  the 
computer's  peripheral  expansion  slots. 
Peripheral  cards  perform  a  variety  of  functions, 
from  controlling  a  disk  drive  to  providing  a 
clock/calendar. 

peripheral  deviccE  See  device. 


phrase:  In  music  synthesis,  a  set  of  pointers  to 
patterns  that  make  it  easy  to  build  repetitive, 
complex  passages  out  of  simple  patterns. 

picture:  A  saved  sequence  of  QuickDraw  drawing 
commands  (and,  optionally,  picture  comments) 
that  you  can  play  back  later  with  a  single 
procedure  call;  also,  the  image  resulting  from 
these  commands. 

pixeli  Short  for  picture  element.  The  smallest  dot 
you  can  draw  on  the  screen.  Also  a  location  in 
video  memory  that  corresponds  to  a  point  on 
the  graphics  screen  when  the  viewing  window 
Includes  that  location.  In  the  Super  Hi-Res 
display  on  the  Apple  IIGS,  each  pixel  is 
represented  by  either  two  or  four  bits.  See  .Iso 
pixel  imaye. . 

pixel  image:  A  graphics  image  picture  consisting 
of  a  rectangular  grid  of  pixels, 

plain-.styled:  Said  of  a  font  or  character  that  is 
not  bold,  italicized,  underlined,  or  otherwise 
styled  apart  from  ordinary  text. 

plane:  ITie  front-io-back  position  of  a  window, 
compared  lo  other  windows  on  the  desktop. 

point;  A  unit  of  measurement  for  type;  12  points 
equal  1  pica,  and  6  picas  equal  1  inch;  thus,  1 
point  equals  ''7:  inch. 

pointer:  (1)  An  item  of  information  consisting  of 
the  memory  address  of  some  other  item.  For 
example,  the  65816  stack  register  contains  a 
pointer  to  the  top  of  the  stack.  (2)  The  mouse 
pointer,  an  arrow-shaped  cursor  whose  screen 
location  is  controlled  by  mouse  movements. 

pointing  device:  Any  device,  such  as  a  mouse, 
graphics  tablet,  or  light  pen,  that  can  be  used  to 
specify  locations  on  the  computer  screen, 

polygon:  Any  sequence  of  connected  lines. 

port:  CD  A  socket  on  the  back  panel  of  the 
computer  where  the  user  can  plug  in  a  cable  lo 
connect  a  peripheral  device,  another  computer, 
or  a  network.  (2)  A  graphic  port  CGrafl»ort). 
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portRect:  The  GrafPon  field  lhat  defines  the 
port's  port  rectangle. 

port  rectangle;  A  rectangle  that  describes  the 
active  region  of  a  GrafPort's  pixel  map^the  past 
that  QuickDraw  II  can  draw  into.  The  content 
region  of  a  window  on  the  desktop  correspoi^ds 
to  the  window's  port  rectangle. 

positfon-lndependent:  Said  of  code  that  can 
execute,  without  modification  of  any  kind,  at  any 
location  In  memory.  Compare  absolute, 
relocatable. 

post:  To  place  an  event  in  the  event  queue  for 
later  processing. 

prefix;  A  pathname  starting  with  a  volume  name 
and  ending  with  a  subdirectory  name,  It  is  the 
part  of  a  full  pathname  that  precedes  a  partial 
pathname— a  prefix  and  a  partial  pathname 
together  constitute  a  full  pathname.  A  prefix 
always  starts  with  a  sla^h  00  because  a  volume 
directory  name  always  starts  with  a  slash, 

prelbt  number:  A  code  used  to  represent  a 
particular  preFix,  Under  ProDOS  l6,  there  are 
nine  prefix  numbers,  each  consisting  of  a 
numeral  followed  by  a  slash:  0/,  I/, ...,&/,  and  V. 

P  register:  See  status  register, 

printing  loop:  The  page-by-page  cycle  that  an 
application  goes  through  when  it  prints  a 
document, 

Print  Manageri  The  Apple  IIGS  tool  set  that  allows 
an  application  to  use  standard  QuickDraw  II 
routines  to  print  text  or  graphics  on  a  primer. 

print  record:  A  record  containing  all  die 
information  needed  by  the  Print  Manager  to 
perform  a  particular  printing  job. 

private  scrap;  A  buffer  (and  its  contents)  set  up 
by  an  application  for  cutting  and  pasting, 
analogous  to  but  apart  from  the  desk  scrap. 

private  symbol:  A  label  in  a  segment  that  may  be 
referenced  by  other  segments  in  the  same  file, 
but  not  by  segments  in  other  files. 
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processor  status  register:  See  status  register, 

ProDOS:  A  family  of  disk  operating  systems 
developed  for  the  Apple  II  family  of  computers. 
ProDOS  stands  for  Professional  Disk  Operating 
System,  and  includes  both  ProDOS  8  and 
ProDOS  16. 

ProDOS  &  A  disk  operating  system  developed  foj 
standard  Apple  II  computers.  It  runs  on  6502- 
series  microprocessors  and  on  the  Apple  lies 
when  the  65816  processor  is  in  6502  emulation 
mode. 

ProDOS  16:  A  disk  operating  system  developed 
for  65SI6  natJve-mode  operation  on  the  Apple 
lies.  It  is  functionally  similar  to  ProDOS  B  but 
more  powerful, 

program  bank  register:  The  65816  register  whose 
contents  form  the  high-order  byte  of  all  3-byte 
code  address  operands. 

prog^-am  counten  See  PC  register. 

program  status  f^eglsten  See  status  register, 

proportionally  spaced:  Said  of  a  font  whose 
characters  vary  in  width,  so  the  amount  of 
honzontal  space  needed  for  each  character  is 
proportional  to  its  width.  Compare  monospaced. 

puU-do^  menu;  A  set  of  choices  for  actions  that 
appears  near  the  top  of  the  display  screen  in  a 
desktop  application,  usually  overiaying  the 
present  contents  of  the  screen  without  disrupting 
them,  Dragging  through  the  menu  and  releasing 
the  mouse  button  while  a  command  is 
highlighted  chooses  that  command. 

purge.-  To  temporarily  deallocate  a  memory 
block.  The  Memory  Manager  purges  a  block  by 
setting  iis  master  pointer  to  NIL  (0).  All  handles 
to  the  pointer  are  still  valid,  so  the  block  can  be 
reconstructed  quickly.  Compare  dispose. 
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purge  level;  A  memory  block  attribute,  indicating 
that  the  Memory  Manager  may  purge  the  block  if 
it  needs  additional  memory  space.  Purgeable 
blocks  have  different  purge  levels,  or  priorities 
for  purging;  these  levels  are  set  by  Memory 
Manager  calls. 

queue;  A  list  in  which  entries  are  added  at  one 
end  and  removed  at  Lhe  other,  causing  entries  to 
be  removed  in  ftrst-in,  first-out  (FIFO)  order. 
Compare  stack. 

QuickDraw  n:  The  Apple  IIGS  tool  set  that 
controls  the  graphics  environment  and  drav/s 
simple  objects  and  text.  Other  tools  call 
QuickDraw  II  to  draw  such  things  as  windows. 

QuickDraw  II  Auxiliary:  An  Apple  IIGS  tool  set 
that  provides  extensions  to  the  capabilities  of 
QuickDraw  n. 

quit:  To  terminate  execution  in  an  orderly 
manner.  Apple  liGS  applications  quit  by  making  a 
ProDOS  16  QUIT  call  or  the  equivalent. 

quit  return  stacki  A  table,  maintained  in  memory 
by  ProDOS  l6,  thai  contains  the  User  ID'S  of 
programs  that  want  to  be  reexecuted  after  the 
current  program  quits. 

radio  button;  A  common  type  of  control  in 
dialog  boxes.  Radio  buttons  are  small  circles 
organized  into  families — clicking  any  button  on 
turns  off  all  the  others  in  the  family,  like  the 
buttoris  on  a  car  radio. 

RAM;  See  random-access  memory. 

random-access  memory  (RAM)!  Memory  in 
which  information  can  be  referred  to  in  an 
arbitrary  or  random  order.  Programs  and  other 
data  in  RAM  are  lost  when  the  computer  is 
turned  off  (Technically,  the  read-only  memoTy 
(ROM)  is  also  random  access,  and  what's  called 
RAM  should  correctly  be  termed  read-write 
memory!)  Compare  read-only  memory. 


read-only  memory  (ROM):  Memory  whose 
contents  can  be  read,  but  not  changed;  used  for 
storing  firmware.  Information  is  placed  into  ROM 
once,  during  manufacture;  it  then  remains  there 
permanently,  even  when  the  computer's  power  is 
turned  off.  Compare  random- access  memory. 

rectangle:  One  of  the  fundamental  shapes  drawn 
by  QuickDraw  II.  Rectangles  are  completely 
defined  by  two  points — their  upper-left  and 
lower-right  corners  on  the  coordinate  plane.  The 
upper-left  corner  of  any  rectangle  is  its  origin. 

reentrant:  Said  of  a  routine  that  is  able  to  accept 
a  call  while  one  or  more  previous  calls  to  it  are 
pending,  without  invalidating  the  previous  calls. 
Under  certain  conditions,  the  Apple  IIGS 
Sclieduler  manages  execution  of  routines  that  are 
not  reentrant. 

region:  An  arbitrary  area  or  set  of  areas  on  the 
QuickDraw  coordinate  plane.  The  outline  of  a 
region  must  be  one  or  more  closed  loops. 

RELOAD  segment:  A  segment  that  is  always 
reloaded  from  disk  when  a  program  is  executed, 
even  if  the  program  is  in  a  dormant  state  in 
computer  memory.  Some  programs  require 
RELOAD  segments  in  order  to  be  restartable, 

relocatable:  Characteristic  of  a  load  segment  or 
other  OMF  program  code  that  includes  no 
references  to  specific  address,  and  so  can  be 
loaded  at  any  memory  address.  A  relocatable 
segment  consisLs  of  a  code  image  followed  by  a 
relocation  diaionary.  Compare  absolute, 

relocation;  The  act  of  modifying  a  program  in 
memory  so  that  its  address  operands  correctly 
reflect  its  location  and  the  locations  of  other 
segments  in  memory.  Relocation  is  performed  by 
the  System  Loader  when  a  relocatable  segment  is 
First  loaded  into  memory. 

relocation  dictionary:  In  object  module  format,  a 
portion  of  a  load  segment  that  contains 
relocation  information  necessary  to  modify  the 
memory  image  portion  of  the  segment.  See 
relocadon. 
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resourcer  A  type  of  organization  for  certain 
components  of  Macintosh  fUts.  Resources 
provide  s  convenient  means  for  manipulating 
the  fixed  (unchanging)  parts  of  a  program  file. 

resource  editor s  A  program  for  editing  resources, 
especially  data  in  a  program,  widiout  having  to 
recompile  the  program. 

Hesource  Manager;  The  Macintosh  toolbox 
component  that  retrieves,  manipulates,  and 
disposes  of  resources, 

restart!  To  reactivate  a  dormant  program  in  the 
computer's  memory.  The  System  Loader  can 
restart  dormant  programs  if  all  their  static 
segments  are  siill  in  memory,  If  any  critical  part 
of  a  dormant  program  has  been  purged  by  the 
Memory  Manager,  the  program  must  be  reloaded 
from  disk  instead  of  restarted. 

restartafales  Said  of  a  program  that  reinitializes  its 
variables  and  makes  no  assumptions  about 
machine  state  each  time  it  gains  control.  Only 
restartable  programs  can  be  resurrected  from  a 
dormant  state  in  memory. 

RGB;  Abbreviation  for  red-green-blue,  a  method 
of  displaying  color  video  by  transmitting  the 
three  primary  colors  as  three  separate  signals. 
There  are  two  ways  of  using  RGB  with  computers: 
TTL  RGB,  which  allows  the  color  signals  to  take 
on  only  discrete  values;  and  analog  RGB,  which 
allows  the  color  signals  to  take  on  any  values 
between  their  upper  and  lower  limits. 

ROM;  See  read-only  memory, 

routine:  A  part  of  a  program  that  accomplishes 
some  task  subordinate  to  the  overall  task  of  the 
program. 

RTL  Return  from  Interrupt,  a  65816  assembly- 
language  instruction. 

RTXj  Return  from  Subroutine  (Long),  a  65816 
assembly-language  instruction. 

RTS;  Return  from  Subroutine,  a  65815  assembly- 
language  instruction. 


SANE;  See  Standard  Apple  Numeric 
EnvironmenL 

SANE  Tool  Set  The  Apple  IIGS  tool  set  that 
performs  high-precision  noating-point 
calculations,  following  SANE  standards. 

scaled  font!  A  font  that  is  created  by  the  Font 
Manager  by  calculation  from  a  real  font  of  a 
different  size. 

scan  line:  A  single  horizontal  line  of  pixels  on 
the  screen.  It  corresponds  to  a  single  sweep  of 
the  electron  gun  in  the  video  display  tube. 

scanllne  contro]  byte  (SCB):  A  byte  in  memory 
that  controls  certain  properties,  such  as  available 
colors  and  number  of  pixels,  for  a  scan  line  on 
the  Apple  UGS,  Each  scan  line  has  its  own  SCB. 

Scheduler;  The  Apple  IIGS  tool  set  that  manages 
requests  to  execute  (nieTTupled  software  that  is 
not  reentrant.  If,  for  example,  an  interrupt 
handler  needs  to  make  system  software  calls,  it 
must  do  so  through  the  Scheduler  because 
ProDOS  16  is  not  reentrant.  Applications 
normally  need  not  use  the  Scheduler  because 
ProDOS  16  is  not  in  an  interrupted  state  when  it 
processes  applications'  system  calls. 

Scrap  Manager:  The  Apple  IIGS  tool  set  that 
suppons  the  desk  scrap,  which  allows  data  to  be 
copied  from  one  application  to  another  (or  from 
one  place  to  another  within  an  application). 

scroll:  To  move  an  Image  of  a  document  or 
directory  in  its  window  so  that  a  different  part  of 
it  becomes  visible. 

scroti  bar;  A  rectangular  bar  that  may  be  along 
the  right  side  or  bottom  of  a  window.  Clicking  or 
dragging  in  the  scroll  bar  causes  the  view  of  the 
document  to  change. 

segment:  A  component  of  an  OMF  file,  consisting 
of  a  header  and  a  body.  In  object  flies,  each 
segment  incorporates  one  or  more  subroutines. 
In  load  files,  each  segment  incorporates  one  or 
more  object  segments. 
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segment  kinds  A  numerical  designaiion  used  to 
classify  a  segmem  in  objeci  module  formaL 

self-booting;  Said  of  a  program  thai  executes 
auiomatically  when  the  computer  is  lurned  on  or 
reset. 

sequence:  A  series  of  commands  that  tells  ihe 
computer  what  notes  to  play  and  when, 

serial  interfacet  A  standard  method,  such  as  RS- 
232,  for  transmitting  data  serially  (as  i  sequence 
of  bits). 

serial  port;  The  connector  for  a  peripheral 
device  that  uses  a  serial  interface, 

Shaston;  The  Apple  IlGS  system  font. 

shelL  A  program  that  provides  an  operating 
environment  for  other  programs,  and  that  is  not 
removed  from  memory  when  those  programs  are 
running,  For  e^cample,  the  APW  Shell  provides  a 
command  processor  interface  between  the  user 
and  the  otlier  components  of  APW,  and  remains 
in  memory  when  APW  utility  programs  are 
mnning.  A  shell  is  one  type  of  controlling 
[irogrsin. 

shell  application:  A  type  of  program  that  is 
launched  from  a  shell  and  runs  under  its  control. 
Shell  applications  are  ProDOS  I6  file  type  SB5- 
In  APW,  compilers  and  certain  Shell  commands 
are  shell  applications  that  are  launched  from  the 
APW  SheU. 

shell  callj  A  request  from  a  program  to  the  APW 
Shell  to  perform  a  specific  function. 

shut  down;  To  remove  from  memory  or 
otherwise  make  unavailable,  as  a  tool  set  that  is 
no  longer  needed  or  an  application  that  has  quit. 

slic  box;  A  small  square  in  the  lower-right  corner 
of  some  windows,  with  which  the  user  can  resize 
the  window.  The  size  box  corresponds  to  the 
^xiw  region. 

65C8I6:  The  version  of  the  6S8I6  microprocessor 
used  in  the  Apple  IIGS,  The  65C816  is  a  CMOS 
device. 


65816:  A  general  term  for  the  type  of 
microprocessor  used  in  the  Apple  IIGS.  The 
65816  is  related  to,  but  more  advanced  than,  the 
6502  microprocessor.  It  has  a  l6-bit  data  bus  and^ 
a  24 -bit  address  bus. 

658I6  assembly  language:  A  low-level 
programming  language  written  for  the  65816 
family  of  microprocessors, 

6502:  The  microprocessor  used  in  the  Apple  II,  in 
the  Apple  II  Plus,  and  in  early  models  of  the 
Apple  He,  The  6502  is  an  NMOS  device  with  an  8- 
bit  data  bus  and  a  l6-bit  address  bus, 

640  mode:  An  Apple  IIGS  video  display  mode. 
640  pixels  horizontally  by  200  pbcels  vertically. 

slot:  A  narrow  socket  inside  the  computer  where 
the  user  can  install  peripheral  cards.  Also  called 
an  expansion  slot 

SmartPort!  A  set  of  firmware  routines  supporting 
multiple  devices  connected  to  the  Apple  IIGS  disk 
port. 

software;  A  collective  term  for  programs,  the 
instructions  that  tell  the  computer  what  to  do. 
Software  is  usually  stored  on  disks.  Compare 
firmware,  hardware. 

Sound  Tool  Set;  The  Apple  lies  tool  set  that 
provides  low-level  access  to  the  sound  hardware. 

source;  See  source  location. 

source  flle:  An  ASCII  file  consisting  of 
instmctions  written  in  a  particular  language,  sucli 
as  Pascal  or  assembly  language.  An  as-sembler  or 
compiler  converts  source  files  into  object  files. 

source  location;  The  location  (memory  buffer  or 
portion  of  the  QuickDraw  II  coordinate  plane) 
/mm  which  data  such  as  text  or  graphics  are 
copied.  Compare  destination  loc^on.  See  also 
source  rectangle; 

source  rectangle;  The  rectangle  (on  the 
QuickDraw  II  coordinate  plane)  from  which  text 
or  graphics  are  taken  when  transferred 
somewhere  else.  Compare  destination  rectangle. 
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special  memory:  On  an  Apple  IICS,  all  of  banks 
$00  and  $01,  and  all  display  memory  in  banks 
$E0  and  $E1  .  It  is  ihe  memory  directly  accessed 
by  standard-Apple  n  programs  running  on  the 
Apple  EGS, 

spool  printing:  A  two-Slep  printing  methocl  used 
to  print  graphics  on  the  ImageWriter.  In  the  first 
step,  it  writes  oui  (spools)  a  representation  of 
your  document's  printed  image  to  a  disk  file  or 
to  memory.  In  the  second  step,  this  information 
IS  converted  into  a  bit  image  and  printed. 
Compare  draft  printing. 

S  reglsten  See  stack  renter. 

stacki  A  list  in  which  entries  are  added  (pushed) 
and  removed  (pulled)  at  one  end  only  (the  top 
of  the  stack),  causing  them  to  be  removed  in  last- 
in,  first-out  aiFO)  order.  The  stack  usually  refers 
to  the  particular  stack  pointed  to  by  the  658l6's 
stack  renter.  Compare  queue. 

stack  pointer:  See  stack  register, 

stack  register:  A  register  in  the  65816  processor 
that  indicates  the  next  available  memory  address 
in  the  stack. 

Standard  Apple  Numerics  Environment 

(SANE):  The  set  of  methods  that  provides  the 
basis  for  floating-point  calculations  in  Apple 
computers,  SANE  meets  alt  requirements  for 
exiended'precision,  floating-point  arithmetic  as 
prescribed  by  IEEE  Standard  754  and  ensures 
that  all  floating-point  operations  are  performed 
consistently  and  return  the  most  accurate  results 
possible. 

standard  Apple  H:  Any  computer  in  the  Apple  II 
family  except  the  Apple  IIGS.  'Iliat  includes  the 
Apple  II,  the  Apple  II  Pius,  the  Apple  He,  and  the 
Apple  lie. 

Standard  Fife  Operations  Tool  Seti  The  Apple 
lies  tool  set  that  creates  a  standard  user  interface 
for  opening  and  dosing  files. 


standard  linker  CAPW):  One  aspect  of  the  linker 
supplied  with  APW.  The  operation  of  the 
standard  linker  is  automatic.  Compare  advanced 

standard  window  parts:  The  window  features  that 
allow  the  user  to  scroll  through  the  data  in  the 
window,  change  the  window's  shape,  or  close  the 
window.  Thty  also  provide  information  about  the 
document  currently  displayed  in  the  window. 

STAHT;  The  name  of  the  program  in  the 
SYSTEM /subdirectory  of  the  startup  disk  that  is 
launched  automatically  when  the  system  is 
booted.  STAJIT  is  typically  a  finder  or  program 
launcher. 

start  up:  To  get  the  system  or  application 
program  running. 

static  segment!  A  program  segment  that  must  be 
loaded  when  the  program  is  started,  and  cannot 
be  removed  from  memory  until  execution 
terminates.  Compare  dynamic  segmenL 

static  text:  Text  on  the  screen  that  cannot  be 
altered  by  the  user. 

status  register:  A  register  in  the  65816 
microprocessor  that  contains  flags  reflecting  the 
various  aspects  of  machine  state  and  operation 
results. 

string:  A  sequence  of  characters.  See  C  string, 
Pascal  string, 

structure  region:  An  entire  window;  its  content 
region  plus  its  firame  region. 

Style  dialog  box;  A  dialog  box  that  allows  the 
user  to  specify  formatting  information,  page  size, 
and  printer  options, 

styled  variation:  An  italicized,  boldfaced, 
underlined,  or  otherwise  altered  version  of  a 
plain-styled  character  or  font. 

subdirectory:  A  file  that  contains  information 
about  other  files.  In  a  hierarchical  file  system, 
files  are  accessed  through  the  subdirectories  that 
reference  them. 
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subfOudiie=  A  part  of  a  program  that  can  be 
executed  on  request  from  anolhcr  point  m  the 
prc^rm  .r.d  that,  upon  completion,  returns 
control  to  the  point  of  the  request, 
super  Hl-Resr  Either  of  two  high-tesoluUon  Apple 
Tl  ^^Xy  -odes.  320  mode  --ists  of  .n 
array  of  pixels  320  wide  by  200  h.gh,  w.th  l6 
avTble'colors,  640  mode  .s  an  array  640  wide 
by  200  high,  with  16  available  colors  (with 
resirictioris). 

transfer.  execuUon  among  several  applications, 
switch  evenu  An  event  type  reserved  for  future 
^  such  as  in  conjuncUon  with  a  switcher. 
sya^nc  «fe«ace=  A  name  or  label,  ^^ch  as  the 
7.To^  a  subroutine,  that  is  used  to  -J^^^  -  ^ 
LaUon  in  a  program.  When  a  f  ^J^"^^^ '"^f  ^' 

symbolic  references  are  resolved; jY^cnJ^ 
program  is  loaded,  actual  memory  addresses  are 
patched  into  the  program  to  replace  the 
symbolic  references.  (This  process  is  called 
relocation.) 


synthesizer!  CD  A  hardware  device  capable  of 

sound  digitally  and  converUng  U  into  an 
analoR  waveform  that  you  can  hear.  ay 
analogy,  any  sound^making  entity,  such  as  the 
Note  Synthesizer  tool  set 
cvstem  disfc  A  disk  that  contains  the  operaung 
^ter^and  other  system  software  needed  to  mn 
applications. 

svstem  event  mask:  A  set  of  flags  that  control 
^Te^nt  types  get  posted  into  the  event  queue 
by  the  Event  Manager. 

svstem  failure:  The  unintentional  lerrnination  of 
pJo^Tm  execution  due  to  a  severe  software  error. 
SvstemPaaure  Manager;  A  pan  of  the 
ScUaneous  Tool  Set  that  processes  fatal  errors 
by  displaying  a  message  on  the  screen  and 
halting  execution. 


associated  with  each  open  ProDOS  l6  f^^l^  ^yery 

assigned  to  them.  By  mampulatmg  the  system  me 
tevef  a  controlling  program  can  easily  close  or 
nush"  files  opened  by  its  subprograms, 
system  folder;  "Hte  SYSTEM /subdirectory  on  a 
ProDOS  l6  system  disk. 

svstem  library  pr^  ProDOS  16  prefix  number 
Tir.^^slc  directory  containing  library 
files  used  by  system  software. 

the  Memory  Manager, 
^tem  menu  bar:  The  menu  bar  that  always 
^Toears  at  the  top  of  the  screen  in  desktop 
fp^-caUons.  It  c'ontains  all  of  *e  common^, 
used  funchons.  in  menus  such  as  File,  Edit,  and 

on. 


system  prefix  (ProDOS  8>:  The  one  prefix 
maintained  by  ProDOS  8. 

system  software:  The  components  of  a  computer 
that  support  appUcaUon  programs  by 

sysieiii  u  *  such  as  memory  and 

managing  system  resources  su«-ii  * 

I/O  devices. 

system  window:  A  window  in  which  a  desk 
accessory  is  displayed. 

task  code:  A  numeric  value  assigned  f  Oie  result 
^eaS  event  handled  by  TaskMaster.  Compare 
event  code. 

task  mask:  A  parameter  passed  to  TaskMaster 
^ci^g  whfch  types  of  events  TaskMaster  is  to 
respond  to. 
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TaskMasten  A  Window  Manager  rouUne  that 
handles  many  typical  evenis  for  an  application. 
Applications  may  caJl  TaskMaster  instead  of 
CetNextEvent 

template:  A  data  structure  or  set  of  parameters 
that  defines  the  characteristics  of  a  desktop 
feature,  such  as  a  window  or  control.  The 
NewWindow  parameter  list  is  a  template  that 
defines  the  appearance  of  a  window  to  be 
opened  by  the  NewWindow  call. 

text  based  interface!  An  interface  between 
computer  and  user  in  which  all  screen  drawing 
(or  other  output)  consists  of  characters.  The  form 
of  each  character  is  stored  in  ROM  and  can  be 
involved  with  a  single  byte  of  data,  Compare 
graphic  fnterfaoe. 

text  bufTer:  A  1-bii-per-pixel  pixel  image  reserved 
for  the  private  use  of  the  QuickDraw  II  text- 
drawing  call. 

text  file:  A  file  consisting  of  the  ASCII 
representation  of  characters. 

text  mode:  One  of  16  possible  interactions 
between  pixels  in  text  being  drawn  to  the  screen 
and  pixels  on  the  screen  that  fall  under 
characters  being  drawn.  Compare  drawing  mode. 

Text  Tool  Set  An  Apple  II OS  tool  set  that 
provides  an  interface  between  Apple  11  character 
device  drivers  and  applications  running  in  native 
mode. 

320  mode:  An  Apple  liGS  video  display  mode, 
320  pixels  horizontally  by  200  pixels  vertically. 

tick  count-  The  (approximate)  number  of  60th 
second  intervals  since  system  startup, 

title  bar:  The  horizontal  bar  ai  the  top  of  a 
window  that  shows  the  name  of  the  window's 
contents.  The  user  can  move  the  window  by 
dragging  the  title  bar 

tooL  See  tool  set 


toolbox:  The  collection  of  built-in  routines  on 
the  Apple  IIGS  that  programs  can  call  to  perform 
many  commonly  needed  functions.  Functions 
within  the  toolbox  are  grouped  into  tool  sets. 

tool  calfc  A  call  to  a  hinction  within  a  tool  set. 

Tool  Locator:  The  Apple  IIGS  tool  set  that 
dispatches  tool  calls.  The  tool  locator  knows  and 
retrieves  the  appropriate  routine  when  you  make 
a  tool  call. 

Tool  Pointer  Table  CTPT);  A  table,  maintained  by 
the  Tool  Locator,  that  contains  pointers  to  all 
active  tool  sets. 

tool  set:  A  group  of  related  routines  (usually  In 
ROM)  that  perform  necessary  functions  or 
provide  programming  convenience.  They  are 
available  to  applications  and  system  software. 
The  Memory  Manager,  the  System  Loader,  and 
QuickDraw  II  are  Apple  IIGS  tool  sets. 

tool  table:  A  list  of  all  needed  too!  sets  and  their 
minimum  required  versions.  An  application 
constructs  this  table  in  order  to  load  its  KAM- 
based  tool  sets  with  the  LoadTools  call. 

track:  (1)  One  of  a  series  of  concentric  circles 
magnetically  recorded  on  the  surface  of  a  disk 
when  it  is  formatted.  Each  track  is  further  divided 
into  sectors.  Each  sector  can  hold  several  K  of 
data.  (2)  A  grouping  of  items  in  a  musical 
sequence.  The  Note  Sequencer  supports  multiple 
tracks  lo  facilitate  writing  multi- instrument  music, 

transfer  mode;  A  specification  of  which  Boolean 
operation  QuickDraw  should  perform  when 
drawing,  See,  for  example,  XOR, 

TRUE:  Nonzero.  The  result  of  a  Boolean 
operation.  Opposite  of  FALSE, 

TTL  RGB:  A  type  of  color  video  consisting  of 
separate  red,  green,  and  blue  signals  that  can 
have  only  discrete  values. 
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typ«ID:  A  subfield  of  ihe  User  ID.  The  User  ID 
Manager  assigns  a  typelD  value  based  on  the 
type  of  program  (application,  lool  set,  and  so 
on)  requesting  the  memory. 

unhlghUght;  To  restore  to  normal  display. 
Selected  conuols,  menu  items,  or  other  objects 
may  be  highlighted  (usually  displayed  in  inverse 
colors)  while  in  use.  and  unhighlighied  when  not 
id  use. 

untoad:  To  remove  a  load  segment  from 
memory.  To  unload  a  segment,  the  System 
Loader  does  not  actually  "unload"  anything;  it 
calls  the  Memory  Manager  to  either  purge  or 
dispose  of  the  memory  block  in  which  the  code 
segment  resides. 

unlock:  To  permit  the  Memory  Manager  to  move 
or  purge  a  memory  block  if  needed.  Opposite  of 
lock 

unmuV3bl&  See  fixed. 

unpack:  To  restore  to  normal  format  from  a 
packed  format. 

unpurgrablC!  Having  a  purge  level  of  zero.  The 
Memory  Manager  is  not  permitted  to  purge 
memory  blocks  whose  purge  level  is  zero. 

updatei  A  type  of  window  event,  signifying  that  all 
or  part  of  the  window  needs  to  be  redrawn. 

update  event:  An  event  posted  by  the  Window 
Manager  when  all  or  part  of  a  window  needs  to 
be  redrawn. 

update  regloni  A  description  of  the  part  of  a 
window  that  needs  to  be  redrawn.  The  Window 
Manager  keeps  track  of  each  open  window's 
update  region. 

User  ID:  An  idenlirication  number  that  specifies 
the  owner  of  every  memory  block  allocated  by 
the  Memory  Manager.  User  ID's  are  assigned  by 
the  User  ID  Manager. 


User  ID  Manager!  A  part  of  the  Miscellaneous 
Tool  Set  that  is  responsible  for  assigning  User 
ID'S  to  every  block  of  memory  allocated  by  the 
Memory  Manager. 

vectori  A  locaUon  that  contains  a  value  used  to 
find  the  entry  point  address  of  a  subroutine, 
vertical  blanking:  The  interval  between  successive 
screen  drawings  on  a  video  display.  It  is  the  time 
between  drawing  the  last  pixel  of  the  last  scan 
line  of  one  frame  and  the  first  pbtel  of  die  first 
scan  line  of  the  next  frame, 
visible  re^on:  The  part  of  a  window  that's 
actually  visible  on  the  saecn.  The  visible  region 
is  a  GrafPort  field  manipulated  by  the  Wmdow 
Manager, 

voices  Any  one  of  l6  pairs  of  oscillators  in  the 

Ensoniq  sound  chip  on  the  Apple  1IG5. 

volume  name!  The  name  of  the  volume  directory. 

wedge:  A  filled  arc,  one  of  the  fundamental 
shapes  drawn  by  QuickDraw  II. 

window:  A  rectangular  area  that  displays 
inFormation  on  a  desktop.  You  view  a  document 
through  a  window.  You  can  open  or  close  a 
window,  move  It  around  on  the  desktop,  and 
sometimes  change  its  size,  scroll  through  it,  and 
edit  its  contents.  The  area  inside  the  window's 
frame  corresponds  to  the  port  rectangle  of  the 
window's  GrafPort 

window  frame:  The  outline  of  the  entire  window 
plus  certain  standard  window  controls. 
Window  Managen  The  Apple  lIGS  tool  set  that 
updates  and  maintains  windows, 
window  menu  bar:  A  menu  bar  that  appears  at 
the  top  of  the  active  window,  below  the  system 
menu  bar.  Window  menu  bars  can  contain 
document  titles,  applications,  and  functions. 

window  record;  The  internal  representation  of  a 
window,  where  the  Window  Manager  stores  all  llie 
information  it  needs  for  its  operadons  on  that 
window. 
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word;  Oti  Lhe  Apple  IICS,  a  l6-bit  C2-byie)  data 
type.  Compare  long  word. 

X  flag:  One  of  three  flag  bits  in  the  65816 
processor  that  programs  use  to  control  the 
processor's  operating  modes.  In  native  mode,  the 
setting  of  the  x  flag  determines  whether  the  index 
registers  are  8  bits  wide  or  16  bits  wide.  See  also 
e  flag  and  m  fla^ 

XOR;  Ex  elusive -OR.  A  Boolean  operation  in 
which  [he  result  is  TRUE  if,  and  only  if,  the  two 
items  being  compared  are  unequal  in  value. 

X  register;  One  of  the  two  index  registers  in  the 
658I6  microprocessor. 

Y  register!  One  of  the  two  index  registers  in  the 
65816 

microprocessor. 

zero  page:  The  first  page  (256  bytes)  of  memory 
in  a  standard  Apple  II  computer  Cor  in  the  Apple 
II GS  when  running  a  standard  Apple  II  program). 
Because  the  high-order  byte  of  any  address  in 
this  part  of  memory  is  zero,  only  a  single  byte  is 
needed  to  specify  a  zero-page  address.  Compare 
direct  pag't. 

loom  box:  A  small  box  with  a  smaller  box 
enclosed  in  it,  found  on  the  right  side  of  the  title 
bar  of  some  windows.  Clicking  the  zoom  box 
expands  the  window  to  its  maximum  size;  clicking 
it  again  returns  the  window  to  its  original  size. 

zoom  area:  The  window  sub  region  that 
corresponds  to  the  200m  box. 
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Bibliography 


Here  are  four  categories  of  books  that  can  help  you  learn  more 
about  desktop  programming  on  the  Apple  IIGS.  We  list  only  a  few 
titles  in  each  category;  many  more  books  are  available. 

Several  of  the  books  listed  below  are  part  of  the  Apple  IIGS 
technical  suite.  See  "Introduction  to  the  Programmer's 
Introduction"  for  other  titles  in  the  suite. 


Apple  IIGS  technical  manuals 

In  this  category,  the  most  important  book  for  writing  programs  is 
the  toolbox  reference  manuah  You  cannot,  write  desktop 
applications  without  it 

Appie  lies  Firmware  Reference.  Reading,  Mass.:  Addis  on- Wesley, 
1987. 

Apple  HGS  Hardware  Refererics.  Reading,  Mass.:  Addison-Wcslcy, 
1987. 

Apple  IIGS  ProDOS  16  Reference.  Heading,  Mass.;  Addison- Wesley, 
1987. 

Apple  IIGS  Toolbox  Reference,  Volumes  1  and  2.  Reading,  Mass.: 
Addison-Wesley,  1987, 

Technical  Intradnciion  to  the  Appie  lies.  Reading,  Mass.; 
Addison- Wesley,  1986. 
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Programming  manuals 

This  category  includes  both  books  and  development 
environments,  APW  (Apple  IIGS  Programmer's  Workshop)  is 
essemial  if  you  plan  to  compile  and  modify  HodgePodgc.  The 
usefulness  of  the  other  books  depends  on  which  languageCs)  you 
are  programming  in.  This  lisl  is  by  no  means  complete: 
additional  books  for  these  and  olher  Apple  IIGS  programming 
languages  are  available, 

❖  APDA;  Books  marked  "lAPDAl'  are  distributed  through  the 
Apple  Programmer's  and  Developer's  Association.  See 
Chapter  p. 

Apple  IIGS  Programmer's  Workshop  Assembler  Reference. 
Cupertino,  Calif.:  Apple  Computer,  Inc.,  1987.  [APDA] 

Apple  IIGS  Programmer's  Workshop  C  Reference,  Cupertino, 
Calif.:  Apple  Computer,  Inc.,  1987.'  [APDA] 

Apple  ncs  Programmer's  Workshop  Reference.  Cupertino,  Calif.; 
Apple  Computer,  Inc.,  1987.'  [APDAJ 

Eyes,  David,  and  Ron  Lichty.  Programming  the  65816.  Including 
the  6502,  65C02,  and  65802.  New  York:  Prentice  Hall  Press.  1986. 

Jensen,  Kathleen,  and  Niklaus  Winh.  Pascal  User  Manual  and 
Report.  3rd.ed.  New  York:  Springer- Verlag,  1982. 

Kernighan,  Brian  W.,  and  Dennis  M.  Ritchie.  The  C  Programming 
Language.  Engelwood  Cliffs,  N,  J.:  PrenUce-HaO,  1978. 

ORCA/  Pascal:  A  Pascal  Compiler  and  Development  System  for 
the  Apple  IIGS.  Albuquerque,  N.  M.;  The  Byte  Works,  Inc.,  1987.* 

TML  Pascal  for  the  Apple  IIGS.-  User's  Guide  and  Reference 
Manual  (APW  veTSian).  Jacksonville.  Fla.:  TML  Systems,  Inc., 
1987/ 


■  Includes  software, 


All-Apple  manuals 

Here  nolfi  especially  the  Human  Inierface  Guidelines  book^it 
contains  a  wealth  of  information  to  help  you  design  your  progra 
for  maximum  efreclivencss  and  ease  of  use. 
Apple  Nuntertcs  Manual.  Reading,  Mass.:  Addison-Wesley,  1987. 
Human  Interface  Guidelines:  7?jc  Apple  Desktop  Inierface. 
Reading,  Mass,:  Addison-Wesley,  19S7. 


Macintosh  programming  manuals 

These  books  are  included  because  many  desktop  concepts, 
although  developed  originally  for  ihe  Macinlosh.  are  direcUy 
applicable  to  the  Apple  IIGS.  Remember,  though,  that  details  of 
implemeniation  are  often  quite  differenil 

Cheraicoff,  Stephen.  Macintosh  Revealed.  Volume  One.-  Unlocking 
the  Tooidox.  Hasbrouck  Heights,  N.  J.:  Haydcn  Book.  1985, 

Chernicoff,  Stephen.  Macintosh  Revealed.  Volume  "hvo: 
Programming  With  the  Toolbox.  Hasbrouck  Heights,  N,  J.i 
Hayden  Book,  1985. 

Inside  Macintosh,  Volumes  f-V.  Reading,  Mass.:  Addison-Wesley, 

1987, 

Prograntmer's  Introduction  to  the  Macintosh  Family.  Reading, 
Mass.:  Addison-Wesley,  1988. 
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'About...'  dialog  boxes  31, 

"About  Hodgepodge-  dialog  box 
39 

absolute  code  24,  196,  226-227, 

vs.  relocatable  code  24,  227 
access  byte  215 
accessing  files  162-165 
accumulator  4,  66,  294 
action  routine  CNDA}  265 
activate  events  68,  69,  72,  73 
aCtlvateEvt  69 
acttvalLng  73 
active  controls  128,  129 
active  windows  114-116 
AddloHenu  55,  59,  120,  154,  305, 
306 

AdjWind  57,  59,  155 

advanced  linker  iAPW)  223  ,  235, 
236 

alert  box  135 

default  button  135 
template  for  creating  140 

alerts  135-136 
Caution  Alert  135 

programming  techniques  l41 
sound  in  135 
Stop  Alert  135 
alert  windows  110,  111,  ll6,  136 
ALLOCJNTERRUPT  272 
Alternate  Display  Mode  157 
APDA  (Apple  Programmer's  and 
Developer's  Association)  xix, 
35,  224  ,  278 


applEvt  69 

Apple  Certified  Developer 

278-279 
Apple  Desktop  Bus  2,  S,  21,  174 
Apple  Desktop  Bus  Tool  Set  21, 

174 

Apple  menu  31,  47,  75,  147 
Apple  Programmer's  and 
Developer's  Association 
CAPDA)  xix,  35,  224,  278 
AppleTalk  2,  8,  9,  l67 
Apple  II   13,  21 

deRned  xxl 
Apple  Itc  xxi,  7,  8,  13,  290 
Apple  lie  xxi,  7-9,  13,  174,  290 
Apple  I  ICS.  See  also  ProDOS  8  s 
ProDOS  16|  programming 
techniques 
built-in  I/O  8-9 
clock-calendar  9 
clock  speeds  4 

compatibility  with  standard  Apple 

II    9-10,  291-292 
Control  Panel  9 
disk  port  8 
execution  modes  4 
firmware  xviii 
game  I/O  connectors  2,  8 
general  xiii-xxii,  2-27 
hardware  xvil 
keyboard  2,  8 
memory   1,  4,  5-6 
microprocessor  2,  3-5 
programming  (generaO  Jtvii 
registers  4 

serial  I/O  ports  2.  8,  9 
slots  2,  6,  8^9 


sound  2,  8,  174 
video  2,  6-7 
Apple  IIGS  Debugger  224. 

24S-253 
Apple  IIGS  Programmer's 

Workshop  (APW)  xviii,  26-27. 
65,  205,  220-225,  296 
advanced  linker  223,  235,  236, 
238 

assembler  xviii,  222 
C  compiler  xvill,  222 
editor  222 

language  considerations  225 
linker  222 

para  meter- passing  225 
program  descriptions  221-224 
Shell   199,  221-222,  259.  261 
standard  linker  223,  235,  238 
utilities  223 

Compact  223 
Crunch  223 
DumpOBJ  223 
Equal  224 
Files  224 
Inil  224 
MacGen  224 
MakeLib  224,  238 
Search  224 
Apple  lies  Toofbox  ^vrfr,  17-22. 
42,  62-106,  108-144, 
146-183  See  aUo  tool  sets  or 
specific  routine/toot  set 
calls  (typographic  convention  for) 
xxii,  36 

compared  to  Macintosh  284— 2S9 
constants  38 
data  structures  38 
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errors  65,  66,  67 
macros  65 

memojy  requiremenls  5 
Apple  II  Plus  xxi,  8,  9,  290 
applicaiion<lefined  events  69,  73 
application  prenx  209 
applications  256-259 
hybrid  292-293 
programming  techniques  26, 

228-229,  256-259 
resiartable  259 
seif-booting  257-258 
application  system  disk  300-301 
application  windows  1 1 1 
APW.  See  Apple  11 GS 

Programmer's  Workshop 
arc  (QuickDraw  II)  87,  91 
ascent/ascent  line  93 
AskUaor  59,  121,  l63,  211,  306 
assembler  (AplSO  xviii,  222 
assembly  language  xiv,  4,  65,  225, 
234 

Hodge  Podge  and  65-66,  190. 

202,  311-376 
programming  examples  190, 
193,  239-246,  263,  265, 
311-376 
programming  techniques  4, 

283-284,  290 
typographic  convention  for  xxii 
attrAddr  187 
attrBank  187 
attrFixed  187 
attributes  word  188 
attrLocked  187 
attrNoCross  187 
AttrHoSpee  187 
attrPaqe  167 
attrPurge  187 
auto-key  events   69,  71-72 
autoKeyEvt  69 
auxlD  field  192-194 
auxiliary  type  field  (ProDOS)  217 
auxiliary  type  file  attributes  217, 
218 

background  colors  92 
background  pattern  85 


background  pbtels  93 
background  procedure  173 
backup  bit  215 
bank- boundary  limited  187 
banks.  See  memory  banks 
bank  zero  4,  6,  192,  203,  248, 

267-270,  293-396 
base  1  ine  93 
batch  mtxie  13 
Battery  RAM  routines  181 
BcginUpdate  115,  118,  134 
bit  images  286 
bit  pianes  98 

black  and  while  drawing,  QuickDraw 

II  103 
blocks.  Sss  memory  blocks 
boot  prefix  209 
bollom  scroll  bar  ]  10 
boundary  rectangle  80-**,  103 
boundsRect  80 

breakpoints,  (debugging)  250-251 
built-in  intermpt  handler  267 
built-in  I/O  2,  8-9 
Busy  Rag  157,  182,  183 
buttons   125,  128,  132-135 

C 

CalcMenuSize  154,  155.  165 
Cancel  button  132,  133,  139 
carry  bit.  See  c  flag 
Caution  Alert  135 
C  compiler  (APW)  xviii,  222 
CDA,  See  classic  desk  accessory 
Certified  Developer  278-279 
cnag  66 

CHANGE_PATH  214 
character  devices  173 
character  image  93 
character  origin  93 
characters  92,  93-94 
character  width  93 
check  boxes   125,  128 
checkDiskError  136,  140, 

308-310 
CheckFrontW  50,  II6 
checkToolErrot  46,306-307 
ChooseFont  97 
Choose  Printer  command  (File 

menu)  32,  166,  289 


Chooser   167,  289 

chunky  pixel  organization  98 

circles  90 

C  language  xiv,  xviii,  65,  202.  225, 
230,  234,  259 
Hodgepodge  and  377-412 
programming  examples  190, 
377-412 
classic  desk  accessory, 

programming  examples  263 
classic  desk  accessory  (CDA)  156, 
247,  262,  300.  See  also  desk 
accessories;  new  desk 
accessory 
supporting  157 
writing  263 
CLEAR„BACKUP_BIT  215 
Clear  command  (Edit  menu)  32 
clicking  (mouse)  14,  15,  4s,  110 
Clipboard  32,  92.  159.  I60,  I6I 
clipping  77,  81-fl2,  33,  IDS,  136 
clipping  region  81,  82,  84 
clipRgn  82 
clock-calendar  9 
clock  (microprocessor)  9 
clock  (real-time)  9 
clock  routines  181 
clock  speends  4,  269,  271,  290 
CLOSE   210,  211,  213 
close  box  48,  110,  111,  114 
Qose  command  (File  menu)  32 
CloseDialog  134,  144 
CloseNDA  158 
aoseNDAbyWinPif  57,  158 
ClosePort  97 
close  routine  (NDA)  265 
OoseWindow  57,  114 
closing  files  210 
color  palette  7,  99-100 
colors  98-103 
dithered  101-103 
QuickDraw  II  98-103 
Super  Hi-fies  7,  98 
window  frame  1 1 1 
color  ubies  7,  99-100 
commaHid-line  interface  13 
commands.  See  specific  command 
compaction  188 
Compact  Utility  (APW)  223 
compatibility  (Apple  11)  9-10 
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compiler  XvLLl,  222 

complelB  system  disk  298-300 

coQSUnts 

event  codes  69 

memory-block  attributes  187 

task  codes  71 
toolbox-defined  38,  50 
oonsmicting  menus  149-152 
comem  region  112,  114,  U9 
control  action  procedure  118 
Control-Apple-Escapc  73 
cotiiro!  dennition  procedure  130 
controlling  programs  197,  199, 

259-260 
conUoUing  user  access  lo  files  218 
Control  Manager  20,  64,  71,  117, 

124-131,  158,  264  288 
cojiirol  manipulation  (Hodgepodge) 

130 

Control  Panel  9,  157,  174 
control- related  events, 

programm  ing  techn  iques  129 
controls  20,  116,  117,  124-131 
active  128,  129 
custom  130 
events  and  129-130 
frame  129 
highlighting  128 
inactive  128 
invisible  128 
types  of  124—125 
value   125,  12S.  130 
windows  and  129 
coordinate  plane  76,  77-79,  80 
locations  on  78 
size  of  77 
coordinates 

global  70,  77,  82-84 
local  77,  82-B4,  103,  105, 
117-118 
Copy  command  (Edit  menu)  32, 

141,  159,  160 
COPV  mode  87 
Copy  Pixels  103 
CREATE    210,  213 
Crunch  utility  CAPW)  223 
C  strings  92,  287 
CtlShutDown  58 
CtlStartUp  45 
cursor  116 


cursor  keys  8 

custom  controls  130 

cusiom  menus  H9 

custom  windows  111 

Cut  command  (Edit  menu)  32. 

141,  159,  160 
cutting  and  pasting  159-1 6 1 

iniemally  l60 

large  amounts  of  data  l6l 

private  scrap  l6l 

programming  techniques 
160^161 

publicly  160 

D 

data  area  105,  112,  117 
Data  Bank  register  294,  295 
data  structures  277 

initializing  (Hodgepodge)  38-41 
toolbox-defined  38 
DEALLOCJNTERRUPT  272 
debugging  246-254 
with  Apple  IIGS  Debugger 

248-253 
with  desk  accessories  246-247 
with  Monitor  program  247-248 
default  button 
alert  box  135 
dialog  boxes  139 
default  prefix  208,  209 
default  properties  (windows)  108 
definition  procedures  51,  109,  130, 

136,  149 
delete  l41 
DeleieMliem  154 
Deref  190 

dereferencing  189,  190 
desceniydescent  line  93 
desk  accessories  21,  47,  75, 

156-158,  182.  See  also  classic 
desk  accessory;  new  desk 
accessory 
Apple  menu  and  51 
debugging  with  246-247 

246-247 
HodgePodge  and  158 
Macintosh  156,  289 
programming  techniques 
262-265 


supporting  156-158 
TaskMaster  and  158 
writing  262-265 
desk-accessory  event  69 
deskAccEvt  69 
Etesk  Manager  21,47,  64  .  71. 

156-158,  182,  262-265 
desk  scrap  21,  141,  159 
data  types  l60 
on  disk  l60 
DeskShutDown  58,  158 
DeskSuriUp  45,  153 
desktop,  programming  techniques 

10 

desktop  applications  10,  13,  124 
desktop  features,  supporting  • 

156-161 
desktop  interface  xviii,  xbt-xx, 

1(^13,  20-21,  257 
desktop- interface  tool  sets  20-21 
DESTROY   210,  213 
destroying  files  210 
Developer  Technical  Support  279 
device-driver  events  69,  73 
(device  drivers  69,  l66,  173 
device  independence  12 
device-interface  tool  sets  21 
DIftLOG.ASH  353-360 
dialog  boxes  21,  131-136 
default  button  139 
message  135 
modal  133.  139 
modeless   133,  156 
DIALOG,  cc  400-404 
dialog  items  137-140 

defining  with  a  template  l40, 

285 
disabling  138 
display  rectangle  137,  139 
inactive  controls  as  138 
invisible  138 
item  ID   137,  139 
item  type   137.  138 
Dialog  Manager  21.  Il6.  131-144. 

308 

DIALOG,  PAS  429-433 
dialog  records  137 
dialogs,  programming  techniques 
141 

DialogShutDown  58 

Index  481 


DialogStartUp  45 

dialog  windows  116,136 

dials  125 

digiiaJ  oscillator  chip  (DOO  S,  175 
direct  page  4,  202,  203,  283 
direct-pag^slack  segment 
202-207,  260,  262 
ProDOS  16  default  206 
direct- page/stack  space   192,  203, 
260,  296 
location  and  arrangement  204 
for  tool  sets  42 
direct  register  4,  203,  262.  293, 

294 
disabling 
dialog  items  13S 
interrupts  293 
menus  and  menu  items  116 
148 

disassembling  248 

disassembly,  watching  while  running 

249 
disk  port  8 
disks   14,  298-301 
Disk  II,  slot  for  9 
DispFoEitWindqw  53 
display  rectangle  dialog  items  137, 

139 

DispaseAll   193,  194 
DisposeHandle  57,  190 
disposing  of  memory  handles  194, 
277 

dithered  colors  101-103 
dividing  tine  (menus)  l4a 
DoAboutlteni  55,  l'S2 
DOC  (digiul  oscillator  chip)  8,  175 
DochooseFont  97,121.305 
noChoos^Eltem  56,  l67 
DoCloselteffi  56,  57 
document  coordinates  83 
doairaent  window  110,  111,  133 
DoHenu  54,  153 
DoOpenltem  55,  120,  l63,  305 
DoPrintltem  56,  170 
DoQuitltem  56 
dormant  200,  259 
DoSaveltem  56,  l64,  213 
DoSetMono  56 
DoSatupItsm  l68 
DoSetUpItem  56 


DaTheOpen    121,  211,  305 

double-clicking  (mouse)  71 
Double  Hi-Res  7 
DoWindow  56 

down  arrow  (scroll  bar  part)  126 

draft  printing  171 

drag  area/dragging  71,110,114 

Drag  Window  114,115 

DiawDialog  134 

dfa-wing  contents  of  Windows 

115-116 
drawing  mask  85 
DrawMenuBar  47,  154,  155 
Drawstring  44,94,  106,  143 
□rawTopWi ndow  170 
driverEvt  69 
drivers.  See  device  drivers 
DumpOBJ  utility  (APW)  223 
dynamic  segments  23,  25,  195, 
196,  200.  232 

programming  examples  245 

unloading  246 


ED  ASM  assembler  296 
editable  text  138 
Edit  menu  32,  133 

Clear  comma ivd  32 

Copy  command  32,  14 1,  159, 
160 

Cut  command  32,  141,  159,  160 
Paste  command  32,  Hi  159 
161 

Undo  command  32,  277 
editor  (APW)  222 
8-bit  Apple  n,  See  standard  Apple 
11 

80-CBlumn  texi  display  6,  260 

slot  for  8 
EMShutDown  58 
EMStartUp  43 

emulation  mode  4,  9,  173,  269, 

291.  293 
EndUpdate  115,  134 
EOF  214 

Equal  utility  (APW)  224 
erasing  (QuickDraw  II)  87,  9l 
error  handling  (HodgePodge) 
306-^310 


errors 

Apple  HGS  Toolbox  65,  66,  67 
printing  172 
testing  for  277 

EVENT. ASM  330-336 

EVEWT.CC  385-389 
event  code  69,  73 
event-driven  programming 

techniques  13-16,  51 
event  handling   15-16,  67-75 

51-57 

event  loop.  See  main  event  loop 
Even!  Manager  16.  20,  48,  63, 

67-75 
event  mask  70,  74,  265 
EVENT.  PAS  422^24 
event  queue  68-70 
event  records  67,  70 
events  48-  See  also  specific  event 

compared  to  interrupts  67 

controls  and  129^130 

defined  14.  67 

types  of  69-70,  74 
execution  modes.  See  emulation 

mode;  native  mode 
Exerciser  (ProDOS  l6)  253-254 
expansion  memory  6 
extended  task  event  record  54,  7^!, 
153 

extended  type  179 
external  references  197 


fields  within  records  36 
file  attributes  214 

access  215 

auxiliary  type  217 

creaiton  and  Jast-modification  dale 
and  time  215 
File  menu  32,  133,  l66 

Choose  Printer  command  32, 
166,  289 

Close  command  32 

Open  command  32 

Page  Setup  command  32 

Print  command  32 

Quit  command  32,  58 

Save  As  command  32 

Save  command  50 
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rilename  208 
files  215 

accessing  162-165 

dosing  210 

controlling  user  access  to  218 

creating  210 

destroying   2 10 

flushing  210 

HodgePodge  and  33,  34 

lyo  buffer  210 

opening   162,  210 

reading  211-214 

saving  l64 

■writing  21 1-214 
Files  utility  224 
file  type  215-217,  256 

$04  218 

$06  218 

$B0  218 

$B3   256-259,  261,  297 
iB5   256,  261-262 
$b6  256,  266,  300 
iB7  256,  266,  300 
%BS  256,  265.  300 
SB9  256,  263.  300 
SBA  256,  300 
iCl    215,  218 
filling  CQuickDraw  ID  87,  91 
fill  mode  100 
FindControl  129 
FindMaxWidth  105 
FindWindow  74,  ll4,  115,  129, 
Firmware  xviii,  294 
FixAppleMenu  47,  158 
fixed  address  (memory-block 

atiribuie)  187 
fixed  bank  (memory-block 

attribute)  187 
fixed  (memory-block  attribute) 

187,  189,  195 
fixed  type  (Integer  Math)  179 
FixMenuBar  47 
nag  word  (QUIT)  202 
FLUSH  210 
flushing  files  210 
FMShutDown  58 
FMStartUp  46 

FONt.ASM  361-366 
FONT.  CC  405-408 
font  families  95 


font  height  93 

Font  Manager  21,54,92,94-96 
font  name  95 
font  number  95 

FONT. PAS  434-436 

fonts  21.  34,  92,  94-97 

where  stored  on  disk  96 
font  size  95 
Fonts  menu  33 
font  strike  94 
foni  style  96 
font  subsitution  l67 
font  windows,  Hodge  Podge  and 

34,  53,  lOi-loe,  305 
foreground  color  92 
foreground  pixels  93 
frac  type  (InEegcr  Math)  179 
frame  61 

alert  window  110 

colors  111 

controls  129,  130 

document  window  110 

region  112 

scroll  bars  117,  129.  288,  289 

window  109 
framing  (QuickDraw  Il>  87,  91 
free^form  synthesizer  176 
FroniWindow  57,  154,  l65.  170 
full  pathname  208 
function  number  (tool  seO  66,  274 
FWEniry  294 

G 

game  I/O  connectors  2,  8 
generators  (sound)  176 
GET_EOF  214 
GeiFamlnfo  97,  105 
GET_F]LE_lNFO  214 
GelFonlFlagS  105 
GelFonLlnfo   105,  123 
CET_LEVEL  211 
GET_MARK  214 
CeLNewModal Dialog  134,  l42 
GetKextEveni  48,  68,  70.  73,  74, 
113,  114,  129,  152,  153,  2S6 
GetPen  IO6 
GetPon  52,  53,  97,  134 
CET^PBEFIX  209 
GetTick  181 


GeiWRefCon  52,  53,  57.  154,  I65, 
171 

global  coordinates  70,  77,  82-84 
global  page  (ProDOS  8)  292,  296 

GLOBALS  .  ASM  373-376 

GLOBALS .  pftS  152,  443--446 
global  sjinbols  238 
GLU.  See  Sound  GLU 
go-away  box/area  110,  114 
CrafFon  81^2,  103.  108,  136 
printing  170 

relation  to  windows  108-109 
graphic  ports  76,  81,  103 
graphics  tablets  8 
grow  box/area  48,  114 
GrowWindow  114 

H 

handles  189,  190 
hardware.  See  Apple  UGS 
HeartBeal  181 

HeartBeat  Interrupt  Task  queue 
181 

HidePleaseWait  46,  134 
Hide  Window  ll4 
hierarchical  file  system  288 
high-level  languages  65  282-283, 
290 

highlighting  72.  II6,  128,  153 
high-order  byte,  of  handles  190 
HiliteMenu  54 
Hi-Res  7 

Hi-Res  video  display  7 
Hi  Word  54 
HLock    104,  211 
Hodgepodge   30-60.  See  also 
specific  subroutine 

"About  ,  "  dialog  box  143-144 

assembly  language  65-66,  190, 
202,  311-376 

auxiliary  type  218 

C  377-412 

code-listing  conventions  xxil,  36 
control  manipulation  130 
desk  accessory  suppon  153 
differences  between  the 
languages  69,  74,  105 
direct-page/stack  space  206 
Edit  menu  disabled  161 

Index  4  33 


error  hstndling  306-310 
event  handJIng  51-57 
files  33,  34 

foni  windows  34,  53,  104^106, 
305 

general  description  XX 
languages  35 

Macintosh  resource  equivalents 
285 

main  event  Itxsp  48-50 

main  program  36,  37 

memory- block  atuibuies  188 

menus  31-33.  47,  153 

mouse  events  and  71 

organization  of  35-36 

Pascal  36,  413-446 

picture  files   Z15-217,  216 

picture  windows  33,  52-53, 
103-104,  305-306 

QuickDraw  II  coordinates  and  82 

QUIT  202 

scrolling  and  117 

shutting  down  57,  58-59 

starling  up  38-47,  64 

subroutines  35,  59-60,  302-3O4 

System  Loader  and  195 

TaskMaster  and  51-53,  75,  2S6 

update  routine  116 

User  ID  use  193 

versions  of  35 

windows  56-57,  72,  120-124 
horliontal  blanking  100 
HP. ASM  312-314 
HP.CC  37B-38I 
HP.H  411^12 
HP. PAS  414-418 
Human  Interface  Guidelines 

xix-xx,  n-13,  139,  146,  277 
I  tUnLock  104,  211 
hybrid  applications  292-293 

I 

icons  10,  285,  2S6 
ID.  See  item  ID;  menu  ID;  User  ID 
image  pointer  80 
image  width  80 
ImageWriter  167 
inactive  conlrofs  128 
as  dialog  iiems  138 


inactive  w  in  dows  115 
index  registers  4,  294 
information  bar  110 
IN IT. ASH  315-323 
InitCursor    124,  l65,  170,  309 
InitGlobals  35,  39-^1,  150 
initialization  files  256.  266 
inkialization  segment  196 
initializing  data  stryaures 

(Hodgepodge)  38-41 
Initializing.  5ee  starling  up 
Initial  Load  260 
in  it  rouiine  CNDA)  264 
rnit  utility  (AP^XO  224 
InsertMenu  47 
InsertMltem    154,  155 
InstallFonl   105,  123 
instnimcnt  177 
lnt2Hex  307,  309 
Integer  Maih  strings  179 
Integer  Maih  Tool  Set  22,  179 
integer  type  {Integer  Math)  179 
Inieraaive  programming  13,  14 
international  markets  277 
interrupt  control  routines  181 
interrupt  environment  269 
interrupt  handlers  182,  183,  256, 

267-272 
interrupt  mode  (Note  Sequencer) 

178 

intarrupls  176,  177,  178,  267 

compared  to  events  67 

disabling  293 
IniToString   105,  122.  l65 
InvalRgn    117,  118 
Inverting  (QuickDraw  II)  87,  91 
invisible  controls  128 
invisible  dialog  items  13S 
I/O.  See  also  slots 

buffer  files  210 

built-in  2,  8-9 

serial  ports  8 
lO.ASM  371-372 
item  character  (menu  and  item 

lines)  150 
kemDisable  138 
item  ID 

dialogs  137,  139 

menus   54,  151-152.  155 
Items 


dialog  137-140 

mentis  149 

Note  Sequencer  178 

J 

Job  dialog  box  l69 
joysticks  8 
]sL  294 
JSR  294 

}ump  Table   196,  198 
K 

keyboard  2,  8,  10 

keyboard  equivalents  148,  153 

key-down  events  15,  l6,  69, 

71-72,  73 
IceyDownEvt  69 
KIND  205 

L 

language  considerations  CAP^3^  225 

LaserWriter  167 

launching  under  ProDOS  l6 

200-202 
leading  93 
LEShutDown  58 
LESiartUp  45 
LETexiBox  I42 
LETexiBox2  142 
library  dictionary  segment  238 
library  files  238-239 
licensing  Apple  software  279 
LineEdil  scrap  141,  l6l 
LineEdit  Tool  Set  21,  64,  138,  139, 

141-142 
line  (QuickDraw  II)  87,  88-89 
LinkEd   205,  234 
assigning  load  segments  with 

236 

linker  (APW>  222.  223,  235-238 
Lisa  14 

list  controls  131 
List  Manager  20,  64,  131 
lists  130-131 
ListShuiDown  53 
LisiStanUp  46 

Loader  Dumper  247  ,  249,  250 
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load  Rles  23,  26,  196,  226-229 

order  of  load  segments  in  235 
loading 

applications  (System  Loader) 

198,  199 
relocatable  segments  (System 

loideO  197 
segments  198 
tool  5et5  63 
LoadOne   l&i,  211,  306 
load  segments   194-195,  196,  230, 
231-234 
assigning  with  LinkEd  file  236 
assigning  in  source  code 

234-236 
characteristics  of  232 
difference  from  object  segments 

230 
dynamic  232 
memory  blocks  and  194 
number  of  232 
order  in  load  file  235 
types  of  (System  Loader)  196 
LoadToois  42,  44,  63 
local  coordinates  77,  82-84,  103, 

105,  117-118 
local  references  197 
location  information  76,  79 
Loclnfo  record  76,  79,  81,  103 
locked  handles  187,  189.  195,  277 
longint  type  (Integer  Math)  179 
LoWord  43,  54,  121,  123 

M 

MacGen  utility  i:APW)  224 
Macintosh  13,  14,  17,  l67,  ISO 

Control  Manager  288 

converting  programs  to  the  Apple 
lIGS  282-289 

desk  accessories  156,  289 

file  system  287-283 

Memory  Manager  288 

Print  Manager  289 

QuickDraw  286-2S7 

resources  285 

Kajidard  File  Package  289 

TaskMaster  not  available  286 

toolbox  compared  to  Apple  IICS 
284-289 


Window  Manager  288 
macros  222  65 
MainEvent  35,  36,  SO 
main  event  loop   14-15,  l6,  48,  67 

HodgePodge  and  48-50 
mainID  192 

main  program  (HodgePodge)  36, 
37 

main  routine  233 
MakeATemplate  140,310 
MalceLib  utility  (APW)  224,  238 
manager.  See  tool  sets  or  specific 

tool  set 
HanyWindDlalog  120 
Mark  214 

master  color  values  98 
master  User  [D  192.  193 

DisposeAll  and  194 
math  tool  sets   22,  178-180 
maximum  segment  size  23 
memory  2,  4,  5-6,  76 

allocatable  by  Memory  Manager 
191 

allocation  191-194 
compaction  188 
disposal  193 

minimum  configuration  5 

ElAM  expansion  5 

requirements  (Apple  llGS 
Toolbox)  5 

ROM  expansion  5 

special  187 
memory  banks  6 

SOO  4,  6,  192,  203,  248,  267, 
270,  29j-296 

$01  6,  295 

JEO  6,  295 

iEl  6,  267,  395 
memory  blocks  187,  197,  247 

attributes  187,  188 

disposing  of  194,  277 

handles  to  189 

load  segments  and  194 

pointers  to  189 

purgeable  194,  233 

unlocking  194 
memory  fragmentation  188 
memory  image  228 
Memory  Manager  20,  22,  23,  42, 
63,  180,  186-195,  288 


Memory  Mangier  247 
memory  protection  ranges,  using 
252 

MENU.  ASM  324-329 
menu  bar  115,  146,  l47,  152 
MENU.cc  3B2-384 
menu-event  handling 

(Hodgepodge)  54-56 
menu  ID   54,  55.  151-152,  155 
menu  Interface  13 
menu  items  l46 
disabled  148 

keyboard  equivalent  l49,  153 
menu  lines  149,  265 
Menu  Manager  21,  47,  64,  71, 

146-155,  264 
MENt],PAS  419-421 
menus  10,  14,  21,  11 6,  146.  See 
also  specific  menu/nienu 
command 

accepting  user  Input  152-153 

appearance  148-149 

constructing  149-152 

custom  149 

disabling  ll6 

dividing  lines  148 

Hodgepodge  and  31-33,  47 

modification  of  15^155 

organization  of  149 
MenuSelea  115 
menu  selections,  handling  153 
MenuShutDown  58 
MenuStartUp  45 
menu  title   146,  153 
message  dialog  box  135 
message  (event-record  field)  70 
MIDI  (Musical  Instrument  Digital 

Interface)  178 
mini'palettes  7,  99 
Miscellaneous  Tool  Set  20,  22,  42, 

181-182,  248 
missing  characters/ symbol  95 
MMStartUp  43 
ModalDlalog  14 1,  144 
modal  dialog  boxes  133,  139 
modeless  dialog  boxes  133,  136 
modes  (program)  12,  133 
modifier  key  71 

modifiers  (event-record  field)  70, 
71 
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Monitor  program  267 

debugging  with  247-248 
MountfiootDisk  45,307-308 
mouse  8,  10 

clicks  14,  15,  48 

double-clicks  71 

slot  for  9 
mouse-down  events  IS,  i6,  69,  71, 

73,  129 
mouseDownEvt  69 
mouse  routines  CMIscellararaus  Tool 

Set)  182 
mouse-up  events  69,  71 
mouse upEvt  69 

movable  (memory-block  attribute) 
188 

MoveTo  43.  94,  106.  143 
MTShutDown  58 
MTSlanUp  i3 

multiple-language  programs, 

debugging  252-253 
multiple-segment  programming 

exsmples   24 1-245 
Munger  routine  CMiscdlaneous  Tool 

SeO  162 
Musical  Instrument  Digital  Interface 

CMIDI)  17S 

H 

native  mode  4,  173,  271-272,  274, 
291 

NDA-  See  new  desk  accessory 
new  desk  accessory  (NDA)  156, 
263,  289,  300,  See  also  classic 
desk  accessory;  desk 
accessories 
programming  examples  265 
supporting   157-158,  161 
writing  264-26S 
NewDttem    134,  143 
NewHandle  4],  43,  122,  192,  211 
NEWLINE  211 
NewMenu  47,  149 
NewModalDialog  142,  143 
NewWindow  109,  124 
New  Window  parameter  list  109, 

121,  123 
NIL  190 
Note  Alert  135 


Note  Sequencer    22,  177-178 
Note  Synthesizer  22,  177.  See  also 

sound/sound  hardware 
notXOR  mode  87 
nuil  event  69,  73 
nullEvt  69 
null  prefix  209 
numeric  keypad  8 

O 

object  files  26,  226-229 
object  module  fonnat  xviii,  26, 

198,  226,  257,  296 
object  segments  230-231 
offset  (into  color  table)  99 
OK  button  132,  133,  139 
OMF.  See  object  module  format 
OPEN   210,  211,  213 
Open  commaixi  (File  menu)  32 
OpenFilter  162,  l64,  218,  306 
opening  files  162,  210 
OpenNDA  15a 
OpenPoft  97 
open  routine  {NDA)  265 
OpenWindow  55,  120,  121,  l63, 

305 

operating-environment  tool  sets 

22,  180-183 
operating  systems  xix 

calls  (typographic  convention  for) 
xxii 
origin 
of  character  93 

of  QuickDraw  II  coordinate  plane 
77 

of  rectangle  82 
oscillators  (sound)  17S-176 
ovals  (QuickDraw  II)  87,  90 
overlays  233 

P 

PackBytes  routine  (Miscellaneous 

Tool  Set)  182 
page-aligned  (memory-block 

attribute)  187 
page-down  region  (scroll  bar  part) 

126 

page  settings,  printing  167-168 


Page  Setup  command  (File  menu) 
32 

page-up  region  (scroll  bar  part)  126 
Paint  52-53 

painting  (QuickDraw  II)  87,  91 

Faint  It    52-53,  104,  170 

PAINT. PflS  439-442 

palettes  7,  99-100.  See  also  color 
palette;  color  tables 
standard  (640  mode)  102 
sundard  (320  mode)  lOO 

parameter  lists  (ProDOS  16)  214 

parameter-passing  253  225 

ParamText    14 1 

part  code  1 27 

partial  pathname  208 

parts,  standard  window  llO 

Pascal  65,  202.  225 
Hodgepodge  and  36,  413-446 

Pascal  string  92 

Paste  command  (Edit  menu)  32, 

141,  159,  161 
patching  24,  227 
pathnames  196,  208,  288 

pointer  CQUTD  202 
Pathname  segment  196 
pathname  table  196 
pattern 

Note  SequejTcer  178 

QuickDraw  II  85 
pen  85 

pen  location  84,  85,  92 
pen  mode  86,  173 
pen  pattern  85 
pen  size  85 

permanent  inkialization  filea  266, 
300 

phrase  (Note  Sequencer)  178 
picture  files,  HodgePodge  and 

21*^217,  218 
picture  (QuickDraw  II)  92 
picture  windows,  HodgePodge  and 
33,  52-53,  103-104.  305-306 
pbcel  images  76,  103-104,  112, 
171,  286 
defined  79 
pixels  77,  79 
background  93 
defined  7 
foreground  93 
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relation  to  coordinate  plane 

locations  78 
shape  or  77,  90.  284 
plain-styled  characters  95 
plane  (window)  113,  136 
PMShutDown  58 
PMStanUp  46 
pointers  189-190 
pointing  devices  10,  71 
point  (QuickDraw  11)  88-89 
point  (typesetting)  95 
polygon  (QuickDraw  ID  87,  96 
port  (printer)  l66 
port  (QuickDraw  ID  See  graphic 

ports;  GrafPort 
port  rectangle  81-62,  83,  103,  lOB 

120 
port.SCB  80 
pos  itian-independent 

code/segments  188,  195,  196, 

197 

PPToPort    103,  104,  U8 
PrChooser  l67 
PraoseDoc  170,  172 
PrClosePage    170,  172 
PrDefault  41 
prefixes   208-210,  288 

initial  values  210 
prefix  numbers  208-209 
PRINT.  ASH  367-370 
PBINT.CC  409-410 
Print  command  (File  menu)  32 
priming  166-173 

background  procedure  173 

choosing  a  printer  l66-l67 

draft  171 

errors  172 

GrafPort  170 

page  seuings,  making  167-1 68 

printing  loop  172 

QuickDraw  II  and  170,  172,  173 

spool  172 
printing  loop  172 
Print  Manager  21,  64,  76,  166-173 
289 

PRINT. PAS  437-438 

prim  records  171 

private  scrap  161 

PrJobDialog  170 

ProDOS  8  xix,  9,  207,  257,  290 


global  page  292,  296 
ProDOS  l6  compared  to  291, 
296 

ProDOS  16  QUIT  call  and  202 
ProDOS  file  system  xix,  207-218 
ProDOS  16  Xlx,  10,  199.  200-202, 
257-259,  260 
compared  to  Macintosh  Tile 

system  287-288 
compared  to  ProDOS  8  291,  296 
direct-page/stack  segment, 

derautt  206 
Exerciser  253-254 
interrupt  handling  271-272 
parameter  lists  214 
prefixes  208-210 
QUIT  call  SB,  202 
shell  applications  and  262 
Program  Bank  register  293 
program  descriptions  (AP'*0 

221-224 
program  launcher  201 
programming  examples.  See  also 
Hodge  Podge  or  specific 
routine 

assembly  language  190,  193, 

239-246.  263,  265,  311-376 
C   190.  377-412 
classic  desk  accessor^ff  263 
dynamic-segment  245 
multiple -segment  241-245 
new  desk  accessory  265 
single-segme  nt   24 0-24 1 
programming  techniques 
absolute  vs,  relocatable  segments 

24.  227 
applications  26,  228-229. 

256-259 
assembly  language  4  ,  283^284, 

290 

auxID  field  193 

controlling  programs  25^260 

control-related  events  129 

cutting  and  pasting  I6O-I6I 

desk  accessories  262-265 

desktop  10 

dialogs  and  alerts  141 

Edit  menu  161 

error  testing  277 

event-driven   13-16,  51 


event  handling  70 
file  types  255-274 
general  xvii,  11,  277 
high-level  languages  282-283, 
290 

Hodgepodge,  using  34-36,  276 
hybrid  applications  292-293 
initialization  files  266 
Interactive  13,  14 
interrupt  handlers  270,  271-272 
language  considerations  225 
loading  programs  199 
loading  segments  198 
load-segment  chaiaaeristics  232 
Macintosh  program  conversions 

282-289 
math  computing  178-180 
memory  allocation  191-194 
menu  modification  154-155 
menu  organization  l49 
objea  module  format  and  26 
parameter-passing  225 
Print  Manager  171-173 
restartability  and  C  259 
segmentation   23-25,  219-254 
shell  applications  261-262 
standard  Apple  II  program 
enhancement  290-297 
static  vs.  dynamic  segments  25, 

232-235 
System  Loader  195 
TaskMaster  and  75 
tool  sets  18,  62,  273-274 
window  drawing  103-106, 

115-116 
window  origin,  resetting  120 
window- related  events  113-120 
program  selector  201 
PrOpenDoc  170,  172 
PrOpenPage   170,  172 
PrPicFile    170,  172 
PrStl Dialog  l69 
ptrToPixImage  80 
pull -down  menus.  See  menus 
purgeable  memory  blocks  194, 
233 

purge  level   187,  195 

purging  190,  194,  195,  197,  200 
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Q 

QDAuxShuiOowrt  58 
QDAuxStariUp  45 
QDShuiDown  58 
QDStajtUp  43 
QuickDraw  CMactntoshO  136 
286-287 
relation  :o  QuickDraw  II  75,  77, 
79,  286-287 
QuickDraw  11  20,  42,  63,  75-106, 
170.        also  specific  tcpic 
blade  and  white  drawing  103 
color  96-103 
coordinates  77,  82 
how  ii  draws  85-88 
limits  to  drawing  77 
Macintosh  QuickDraw,  relation  to 

75.  77,  79,  286-287 
pattern  85 

printing  and  170,  172.  173 

text  drawing  92-97 

what  it  draws  88-92 

where  it  draws  76-84 
QuickDraw  II  Auxiliary  20,  75 
QUIT  58,  199,  200-202,  260, 
261-262 

flag  word  202 

in  high-level  langtjages  201 

pathname  pointer  202 
Quit  command  (File  menu)  32,  58 
quit  return  stack  201 

R 

radio  buttons  125,  128 

RAA(  6,  9;  18.  See  aiso  memory 

RAM- based  tool  sets  43,  63 

RAM  expansion  5 

RAM  patches  (tool  sets)  43,  293 

READ  211 

reading  Tdes  211-214 

rectangles  (QuickDraw  ID  87,  89 

data  structure  90 

origin  of  82 
reentrant  code  182 
RefreshDesktop  45 
regions  (QuickDraw  II)  87,  91 

defined  112 
registers  4.  66,  283 


RELOAD  segments  200,  207,  259 
relocatable  code  23,  24,  196,  197, 

226-227,  291,  295 
relocation  dictionary  228 
required  tool  sets  62-63 
resources  (Macintosh)  285 
Restart  200 
restartabiliiy,  C  and  259 
resurtable    197,  200,  259 
rcstart-from-memorjf  Flag  (QUIT) 

202 

restarting  programs  in  memory 

199-200 
return  flag  (QUIT)  202 
RGB  video  2,  7 
right  scroll  bar  110,  111 
ROM  9,  18.  5eB  ako  memory 
ROM  expansion  5 
rounded-corner  rectangle 

(QuickDraw  II)  87,  90 
routines  {Hodgepodge)  35,  59-60. 

303-304.  See  also  specific 

routine 

routines  (tool  set)  17.  See  also 
specific  routine 
how  to  call  65-67 
routine  numbers  66,  274 
total  number  of  62 

RTI  269 

RTL  260,  261,  262,  265 


sample  programs.  See  also 

Hodgepodge;  programming 

examples 
SANE  (Standard  Apple  Numeric 

Environment)  xix-xx 
Save  As  command  (File  menu)  32 
Save  command  (File  menu)  50 
SaveOEie   l64,  l65,  213 
saving  nies  l64 
scaled  fonts  287 

defined  96 
scan-line  control  byte  BO,  100 
Scheduler  22,  1S2-183 
Scrap  Manager  21,  64,  158, 

159-161,  264 
ScrapShulI>own  58 
ScrapStartUp  46 


screen  memory  76,  79 

scroll  bars  72,  llO,  112,  117,  126, 

129   288,  289 
scrolling  73,  112,  117-120 
ScrollRect   117,  118 
Search  utility  (APWO  224 
segmentation    23-25,  228, 
230-238,  284  219-254 

absolute  24 

direa-page/stack  204 

dynamic  25,  195 

maximum  segment  size  23 

object  230-231 

relocatable  24 

static  25.  195 
segmented  programs,  debugging 
249 

SeleclWindow  114 

self-booting  applications  257-258 

257-258 
sequence  (Note  Sequencer)  177 
serial  ports  2,  8,  9.        also  I/O 
SetBackCoIof  43,  94.  143 
SetalParams  127 
SetDAFont    14 1 
SET_EOF  214 
SET_FlLE_[NFO  214 
SetFoniFlags  105 
SelForeColor  43,  94,  143 
SET_LEVEL  211 
SET_MARK  214 
SelMenuFtag   154,  155 
SetMItem  165 
SetMltemID  155 
SeiMTiileStart  47 
SetOriginMask  124 
SetPenMode  17 
SetPenSize  17 
SeiPort  97,  124,  134,  143 
SET_PREFIX  209 
SetRect   39,  40,  41,  104,  122,  123, 
134 

SetTextFace  143 
SetUpDefauit  35,41,168 
SetUpMenus  35,36,47,158 
SetUpWlndows  35,41,123 
SeiWTitle  l65 
SFAIICaps  45 
SFGelPile    162,  163 
SFPuiFile    164,  165 


4aS  Index 


SFShutDown  58 
SFStartUp  45 
shadowed  reaangle  148 
shape  of  pixels  77.  90,  2S4 
Shaston  95 
shell  197 

shell  applications  Z4l,  256,  259, 

261-262 
Shell  CAPW)  199,  221-222,  259, 

261 

^ell  ktentirier  261 
ShowCursot  44 
ShowFoni  53,  97,  105,  170 
showPleaseWait  46,  II6,  134, 
142 

sliutDownTools  35,58,158 
shutting  down   197.  199-200 

Hodgepodge   57.  5B-59 
single-segnvent,  programming 

examples  240-241 
640  mode  7,  SO,  98,  99  102 
65816  miaoprocEssor  xiv,  3-5,  10. 

65,  291 

6502  microprocessor  xxi,  3,  9, 

294-295 
size  box   110,  111,  112.  IH 
size  of  coordinate  piano  77 
Si2eWmdoTW  ll4 

slots  2,  6,  8-9,  166.  Sea  also  I/O 
for  80-columji  texi  display  8 
for  mouse  9 
SmartPon.  slot  for  9 
smoothing  167 
Software  Licensing  279 
SOS  215-217 
Sound  GLU  8,  175 
sound/sound  hardware  2,  8,  9,  22, 
135.  174-176.  See  ako  Note 
Synthesizer 
Sound  Tool  Set  22,  176 
source  files  26,  226-229 
assigning  load  segmenls  in 
234-236 
specialized  tool  sets  22 
special  memory  187 
spool  printing  172 
stack  4,  203.  269,  284,  293,  296 
Slack  overllow  207 
stack  pointer   203.  262,  269,  294 
Stack  underflow  207 


Standard  Apple  Numeric 

Environment  (SANEO  xix-Kt 
Standard  Apple  Numeric 

Environment  Tool  Set  22. 
179-180 
standard  Apple  11  4,  10,  203,  290 
compatibility  of  Apple  IIGS  with 

9^10,  291-292 
dePmed  xxl 

program  enhancement  290-297 
Standard  File  Operations  Tool  Set 

21.  64.  162-165,  288,  289 
standard  linker  (APW)  223,  235. 

238 

standard  window  parts  UO 

START    257,  258 

starling  up 

Hodgepodge   38-47,  64 

tool  sets   38-41,  42-46,  62-67 

startUpTools  35,  36,  42.  158, 
188 

static  segments  25,  195,  196,  200, 

232-235 
static  text    140,  141 
step  mode  (Note  Sequencer)  178 
StopAleit  309 
Stop  Alert  135 
structure  region  112 
Style  dialog  box  l67 
styled  variations  (fonts)  34.  95,  96 
subroutines  230 
Hodgepodge  35,  59L^, 
303-304 

Super  Hi -Res  xviii,  2.  6-7.  98,  284 

available  colors  7,  98 

color  palettes  7 

640  mode  7.  99,  102 

320  mode  7,  99.  101 
switch  events  68,  69,  73 
switchEvt  69 
switching  execution  199 
symbolic  reference  226,  238 
synthesizer.  See  Note  Synthesizer; 

sound/sound  hardware 
SysBeep  routine  (MisceUaneoos 

Tool  Set)  182 
SysFailMgr  307 
SystemClick  158 
system  clock  9 
system  disk  298-301 


application  300-301 

complete  298-300 
SystemEdil  158 
system  event  mask  70 
System  Failure  Manager  176,  131 
system  file  levels  201,  211 
system  library  prefix  209 
System  Loader  22,  23,  180, 
195-200.  259 

loading  applicatkms.  198 

loading  relocatable  segments 
197 

types  of  load  segments  196 
system  menu  bar  147 
system  program  (ProDOS  B)  257 
SYSTEM.  SETUP  /  subdirectory  300 
system  windows  111 

T 

lask  codes  48,  70,  74 
taskData  field  54,153 
task  mask  74 

TaskMaster  48,  50,  51-53,  73-75, 
113-117,  152 
compared  to  GetNextEvent  68 
in  converting  Macintosh  programs 
286 

desk  accessories  and  158 
extended  task  event  record  74 
frame  controls  and  129,  130 
Hodgepodge  and  51-53.  75, 
286 

menu -select  ion  handling  153 
programming  techniques  and  75 
scroll  bars  and  117 
window-related  events  and  115 

templates   140,  285 
temporary  initialization  files  266, 
300 

termination  character  (menu  and 

item  lines)  150 
text   92-97,  104-106 
text  block  92 
text  document  112 
text  mode  92 
text  strings  285 
Text  Tool  Set   21.  173.  26l 
320  mode  7,  80.  98,  99.  147  100 
thumb  (scroll  bar  part)  126.  129 
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tide  bar  110,  111,  114 
tiiJe  character  (menu  and  item  lines) 
150 

TLMoontVolume  307.  308 
TLStartUp  43 

toolbox-defined  consUnts  3S,  50 
toolbox-defined  data  structures  38 
Toolbox.  See  Apple  IIGS  Toolbox 
tool  initialization  134 
Tool  Locator  18,  20,  42,  62,  65-*^, 

272-273 
tool  numbers  273 
tool  sets    17-22,  291,  See  aho 

Apple  IIGS  Toolbox  or  specfic 

toot  set 
advantages  of  using  18 
basic  20 

categories  of  19-22 
defined  17 

desktop-intcrrace  20-21 
device-Interface  21 
direct- page  space  for  42 
fiinaion  numbers  66,  274 
independence  from  operating 

system  18 
loading  63 
math  22 
number  of  62 
numbers  66,  273 
operating-environment  22 
programming  techniques  18,  62, 

272-274 
RAM-based  43,  63 
RAM  patches  43,  293 
required  62-63 
sound  22 
specialized  22 

starting  up  38-41,  42-46,  62-67 
62-67 

user- written  272-274 

version  number  63 

where  stored  on  disk  63 
TOOL. SETUP  300 
tool  table  42,  63 
TrackControl  71.  12? 
Track  GoAway  114,  115 
tracking  153 
Track  Zoom  114 
translation  277 
trigger  value  251 


type  ID  192 
types  36 

U 

underlining  96 

Undo  command  {Edit  menu)  32, 
277 

unhfghlighting  72,  153 
unloading  197,  198,  233.  246 
unlocking  handles  194,  277 
un  purges  ble  195 
up  arrow  (scroll  bar  part)  126 
update  events  68,  69,  72,  115,  118 
updateEvt  69 
Update  region   115,  117 
update  routine,  HodgePodge  and 
116 

updating  72,  73 
user-defined  constants  36 
User  ID  192-194,  201,  202,  241, 

247,  261 
User  ID  Manager  182,  192 
user  interrupt  vector  268,  270 
User  Shutdown  199,  200,  260 
user  tool  sets   256,  272-274 
user- written  tool  sets  272-274 
utilities  CAPW)  223 

V 

value  controls  125,  128,  130 
variable  initialization  (HodgePodge) 

3a-4l 
vector  routines  l8l 
versions  301 

of  HodgePodge  35 

of  tool  sets  63 
video  display  2,  6-7.  See  also 
Super  Hi-Res 

Double  Hi-Res  7 

80-column  text  6,  8,  260 

Hi-Res  7 
visible  region  81,  82,  84,  115 
visRgn  82 
volume  name  208 

W 

WailCursor  46,  l65,  170,  211 


wContDefProe  109 
wedges  91 
wFrame  109 

what  (event-record  field)  70 
when  (event-record  field)  70 
where  (event-record  field)  70 
width  (field  in  Loclnfo  record)  HO 
wlnactMenu  75 
wlncontent  74 
w  I  n  De  s  h  74 
winDeskltem  75 
WINDOW.  ASM  337-352 
WINDOW. cc  390-399 
window  content  definition 

procedures  51 
window  drawing,  progiamming 

techniques  103-106,  115-116 
window  events  51,  72 

HodgePodge  and   56-57,  72 
window  frame  109,111 
window  list  154 

Window  Manager  20,  64,  71-73,  32, 

91,  10&-124  288 
■window  menu  bars  147 
window  origin,  resetting  1 20 
WINDOW. PAS  425-428 
window  records  109 
window- related  events 

programming  techniques 
113-120 

TaskMaster  and  115 
windows  10,  14,  51,  81,  82, 
108-124 

active   114,  115,  116 

alert  110,  111,  II6.  136 

application  111 

basic  features  108-113 

controls  and  129 

custom  111 

default  properties  108 

definition  procedures  51 

dialog   116,  136 

document   110,  111 

draw  ing  contents  of  115-116 

frame  colors  111 

GrafPorts,  relation  to  108-109 

HodgePodge  and   57,  120-124 

inactive  115 

port  rectangle  origin  120 
scrolling  117-120 
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standard  parts  110 

syslem  111 
Windows  menu  32 
wlnDrag  74 
WiindShulDown  58 
WindStartUp  45 
WindStatus  58 
wInFrattie  75 
wInGoAway  74 
wInGrow  74 
wlnlnfo  75 

wInWenuBar  50,54,74,153 
wlnSpeciai  75 
HlnSysWindow  75 
wlnZoom  74 
wRefCon  109 
WRITE   211,  213 
writing  lo  files  211-214 

X 

X  register  66,  26l 
¥ 

Y  regisier  26l 
Z 

zero  page  203,  269,  293,  296 
zoom  box/area  48,  UO,  lU.  112. 
114 

ZoomWindow  114 


Programmer's  Iiita)duction  to  die  Apple  Acs* 

The  Officii!]  PubJicatinn  frt)m  Apple  Computer,  hx. 

Tlie  Apple  Dgm*  pcnsonal  aimputer— with  its  high  speed,  expandable  memory', 
super-high-rewiution  color  graphics,  and  exteiMiw  Toolbox  of  pnjgramiiiing 
rouiines— Ills  created  a  powriiil  new  programming  envirnnmeni.  Written  for 
pR)gramniers  and  software  devcloprrs,  Prognmnmr's hitrodiiction  to  lije  Afple  Hgs 
explaim  essential  concepts  and  provides  lips  and  practical  achice  from  tiK-  designers 
of  tiie  Apple  Dgs  Toolfx)x  and  the  neu'  IVoDOS*  16  operating  swtem, 

To  illustrate  these  concepts,  fmgfotnmer  s  bmoduchsjt^  io  //je?.4/y)/f  //ra  includes 
three  complete  versions  of  a  functioning  sample  pn>gnim  called  llodgcftidge— ui 
65816  assenibly  langtuige,  C,  and  Pascal.  Using  liodgcPodge  a.s  an  example,  the  book 
demonstrates: 

■  Event-driven  progninuning  techniques 

•  Programming  witli  tlie  Apple"  Desktop  user  interfece 

■  Effective  use  of  the  Apple  IIgs  Too1Ix)x 

■  How  to  ^^Tite  scjjnic'nted,  relocatable  code  th;it  will  m;ike  prtignims  run  more  cfTiciently 
-  File  handling 

•  MenK>r\'  maiagemeni 

•  How  to  write  special  ized  pntgranis  such  as  sfiells  and  desk  accessories 

Appendices  include  aiinpleie  source  code  listings  of  1  lodgeRidge  in  all  three 
languageSt  as  well  its  hints  on  comerdng  Apple  Macintosh*  programs  and  earlier  Apple 
D  programs  for  die  Apple  flu?.. 

Prugranmier's  hitroiiiiction  io  tht^  Afple  Ucs  contains  a  3.i-inch  disk  that  includes  both 
source  code  and  execuoble  versions  of  HodgePbdge. 
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